BlackBerry Java SDKVersion: 7.0 Beta

Getting Started Guide

Published: 2011-08-05SWD-1641291-0805032022-001

Contents1 Introduction...................................................................................................................................................... 3

Marketing your app.......................................................................................................................................... 3Designing your app........................................................................................................................................... 4Getting help with Java development................................................................................................................ 5

2 Java development tools.................................................................................................................................... 7About the BlackBerry Java plug-in for Eclipse................................................................................................... 7Simulators......................................................................................................................................................... 7Code signing keys.............................................................................................................................................. 8Install the BlackBerry Java Plug-in and the Eclipse IDE..................................................................................... 8

3 Creating your first BlackBerry Java application................................................................................................ 9Create the Hello BlackBerry application........................................................................................................... 9Running your BlackBerry Java application........................................................................................................ 10

Run your application on the BlackBerry Smartphone Simulator............................................................... 10Run your application on a BlackBerry device............................................................................................ 11

4 Introducing the Java SDK.................................................................................................................................. 13Application lifecycle APIs.................................................................................................................................. 13UI API................................................................................................................................................................ 15Application integration APIs............................................................................................................................. 21PIM APIs............................................................................................................................................................ 26Messaging APIs................................................................................................................................................. 27Network Connection APIs................................................................................................................................. 29CLDC Platform and Utilities APIs....................................................................................................................... 30Device characteristics and BlackBerry infrastructure category........................................................................ 32Data storage APIs.............................................................................................................................................. 33Multimedia API................................................................................................................................................. 34Location-Based Services API............................................................................................................................. 35Security APIs..................................................................................................................................................... 37Support for standard Java APIs......................................................................................................................... 39

5 Find more information...................................................................................................................................... 40

6 Provide feedback.............................................................................................................................................. 41

7 Glossary............................................................................................................................................................ 42

8 Document revision history................................................................................................................................ 44

9 Legal notice....................................................................................................................................................... 45

Introduction 1Welcome to BlackBerry® Java® development. This guide provides all the information you need to get started creatingmobile applications for the BlackBerry smartphone. It provides an introduction to the components of the BlackBerryJava SDK, introduces you to the tools you need to develop BlackBerry Java apps, and shows you the basics of BlackBerryJava app development.

The BlackBerry smartphone is built from the ground up as a Java-based device, with all built-in apps and APIs writtenin Java. The BlackBerry Java SDK includes Java ME APIs and BlackBerry-specific APIs. The BlackBerry APIs provideaccess to advanced UI functionality, deep integration with existing applications, the ability to create databases withSQLite® and use cryptographic functions to protect your content, the functionality to embed location-based features(for example, maps and geolocation functionality), and much more.

The BlackBerry® Java® Plug-in for Eclipse® includes the BlackBerry® Java® SDK, and also includes functionality tosimplify your development efforts: tools to compile your code into the files you need for BlackBerry deployment, aswell as functionality to create apps for multiple versions of BlackBerry device software, debug, and more.

Marketing your appResearch In Motion provides the following solutions to help you achieve success with your apps. All of these servicesare provided free of charge.

The Advertising Service, Payment Service, and Analytics Service are all separate SDKs so that they are not dependenton a BlackBerry® Java® SDK version. These services are designed for easy integration.

Post your app on App World

BlackBerry App World is a vendor portal provided by Research In Motion for you to sell your apps. There is no costto you to register with App World or to use it to sell your apps. App World comes pre-loaded on new BlackBerry®smartphones. Over 90% of the BlackBerry subscriber account base of 50 million has access to BlackBerry App World.App World is available in over 70 countries and supports 21 currencies and 6 languages.

For more information, see:

• BlackBerry App World Distribution• BlackBerry App World storefront developer guides

Place ads in your app

The Advertising Service is an SDK and web portal that you can use to put ads in your apps. The web portal allows youto modify ad content after your app is released.

For more information, see:

• Advertising Service• Advertising Service developer guides and API reference

Collect money in your app

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

3

The Payment Service is an SDK that you can use to collect money in your apps. Your customers can use any of thepayment types associated with their BlackBerry ID. Payment types can include billing to their wireless service provider,credit card, or PayPal. The Payment Service server processes all purchase requests.

For more information, see:

• Payment Service• Payment Service developer guides and API reference

Collect data about usage of your app

The Analytics Service is an SDK and web portal that can help you understand the usage of your apps. For example,you can collect data about BlackBerry smartphone models, versions, countries of origin and language of your users;the number of unique users, the total number of sessions, and the average length of a session; and data such asscreen views, button clicks, and application errors. The Analytics Service collects the data, compiles it, and producesreports and metrics on a web portal.

For more information, see:

• Analytics Service• Analytics Service developer guides and API reference

Designing your appThis section provides some of the basic steps for planning a successful app, with links to more in-depth information.

Research your market

Your first step should be to research your market to determine what your prospective users want. For apps that willbe sold on App World, you should research market potential and current market penetration. For enterprise apps,determine the needs and skill levels of your target users.

Decide your version support

Each BlackBerry smartphone runs a version of BlackBerry Device Software that corresponds to a version of theBlackBerry® Java® SDK. Applications are forward compatible but they may not be backward compatible. For example,apps written in the BlackBerry Java SDK 5.0 run on BlackBerry Device Software 6.0, but may not run on BlackBerryDevice Software 4.7.

For more information about designing apps for multiple versions, see Develop applications for different BlackBerrydevice software versions and BlackBerry smartphone models.

For more information about model characteristics and customer usage of models, see:

• Choosing a target device OS• BlackBerry smartphone models• BlackBerry Java SDK API Reference and BlackBerry Java SDK UI Component Development Guide (for the version

when each API component was introduced)

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

4

In the BlackBerry Java Plug-in for Eclipse, you can package your BlackBerry application project (and its dependentprojects) for multiple versions of BlackBerry Device Software. When you distribute your app with BlackBerry DesktopSoftware or the BlackBerry Enterprise Server push service, the plug-in creates one master .alx file in the Standardfolder of your BlackBerry application project. When you distribute your app over the Internet, the plug-in createsthe .jad and .cod files for each version of the BlackBerry Device Software in the Web folder of your BlackBerryapplication project.

For more information about packaging application projects for multiple versions, see BlackBerry Java Plug-in forEclipse developer guides.

Decide which BlackBerry features to integrate into your app

Successful smartphone apps take advantage of the technology of the smartphone. For example, they integrate withsocial networking, calendars, cameras, GPS, or push capability. Some BlackBerry smartphones containmagnetometers (a three-axis compass that detects direction), accelerometers that detect movement of thesmartphone in 3-D space, NFC sensors that detect tokens and cards, and more.

For information about BlackBerry features and how to make the most of them in your app, see:

• BlackBerry Super Apps• BlackBerry Java SDK Super App Development Guide• BlackBerry Java SDK Integration Development Guide

For more information about the accelerometer and magnetometer, see BlackBerry Java SDK UI and NavigationDevelopment Guide.

For more information about NFC, see:

• Near Field Communication• BlackBerry Java SDK Networking and Connectivity Development Guide

Review BlackBerry Design Guidelines

RIM has conducted extensive research to develop best practices and design tips for you to use when designing anapplication and creating a user interface. For more information, see BlackBerry Java SDK UI Guidelines.

For a quick reference to the UI components you can create, see BlackBerry Java SDK UI Components.

Check out the sample apps

RIM provides many sample applications to help you get started. See Java Sample Apps.

Getting help with Java developmentWhen you have questions or problems, RIM provides resources for you to get help. These include:

Free places to ask questions:

• Support forum for Java developers• Developer issue tracker (to log bugs and check on bug reports)

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

5

• BlackBerry Development on Twitter• BlackBerry Development Facebook community

Fee-based ways you can ask questions:

• Incident-based support for developers• BlackBerry Alliance program

Your question might already be answered. Here is a quick overview of the Java development resources:

• Developer Resources• BlackBerry.com Developer Zone Java getting started page• BlackBerry developer blog• Knowledge base for Java development• Java Development Guides• Java Sample Apps• Java API Reference

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

6

Java development tools 2This section describes the development tools you can use for BlackBerry® smartphone application development.

About the BlackBerry Java plug-in for EclipseEclipse is a free, open source development tool. To extend Eclipse for BlackBerry development, RIM provides theBlackBerry Java Plug-in for Eclipse, also free of charge. The plug-in simplifies Java application development forBlackBerry smartphones while giving you access to standard Eclipse tools, such as code assist.

The BlackBerry Java Plug-in for Eclipse is the preferred development tool to develop BlackBerry Java applications.However, you can alternatively use Visual Studio or NetBeans® as your development environment.

The plug-in includes the BlackBerry Java SDK, the BlackBerry Smartphone Simulator, and many sample applications.The plug-in also includes the following development tools:

• RAPC: You can use this command prompt compiler to compile .java and .jar files into .cod files. Applications ona smart phone must be .cod files.

• JavaLoader: You can use this tool to add or update an application on a smartphone for testing, and to viewinformation about application .cod files.

• BlackBerry Signature Tool: You can use this tool to send code signature requests to the BlackBerry® SigningAuthority Tool.

• Preverify Tool: You can use this tool to partially verify your classes before you load your application onto asmartphone.

• JDWP: You can use this tool to debug applications using third-party IDEs.

There are versions of the BlackBerry Java Plug-in for Eclipse for Windows and Macintosh operating systems.

If you previously developed BlackBerry Java applications with the BlackBerry JDE, you can import your project intoEclipse with the BlackBerry Java Plug-in for Eclipse. After version 1.1, the BlackBerry Java Plug-in for Eclipse no longersupports project files (.jdp) and workspace files (.jdw) and is not backward compatible with the BlackBerry JDE.

More information about Eclipse and the Java plug-in• BlackBerry Java Plug-in for Eclipse Development Guides (for Windows and Mac)• BlackBerry Java plug-in for Eclipse update site• Java tools

SimulatorsWhen you install the BlackBerry® Java® Plug-in for Eclipse®, simulators are downloaded for all BlackBerry modelsthat are supported by the BlackBerry Device Software that you installed. You can download other simulators forother versions.

For more information about simulators, see the BlackBerry Java Plug-in for Eclipse developer guides.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

7

Code signing keysSome BlackBerry® APIs require code signing keys. When you use these APIs, you can test your app in a simulator butcannot deploy until you use your key to sign the application. In the API reference, elements that require code signingkeys are noted with a picture of a lock.

BlackBerry code signing keys are free. To register for code signing keys, visit www.blackberry.com/SignedKeys.

For more information about using code signing keys, see the BlackBerry Java SDK Security Development Guide.

Install the BlackBerry Java Plug-in and the Eclipse IDEBefore you begin:

You must download the BlackBerry® Java® Plug-in setup application. To download the setup application that includesthe Eclipse IDE, visit www.blackberry.com/developers/java.

1. Double-click the setup application file.

2. On the Introduction screen, click Next.

3. Accept or decline the terms of the license agreement.

4. Click Next.

5. Specify an empty folder where you want to install the BlackBerry Java Plug-in and the Eclipse IDE.

6. Click Next.

7. On the Select Additional Tasks screen, select where you want the setup application to create shortcuts for theBlackBerry Java Plug-in.

8. Click Next.

9. Review the information on the Pre-installation Summary screen and click Install.

10. Click Done.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

8

Creating your first BlackBerry Javaapplication

3

The BlackBerry® Java® Plug-in for Eclipse® 1.3 and later provides templates you can use to create a basic BlackBerryapplication project. You can customize the code to suit your needs, or you can create an application from scratch byusing an empty application template.

To get you started, we'll create a version of the "Hello World" application by using the Hello BlackBerry template.This version of "Hello World" is a basic UI application that provides some simple UI components. The applicationincludes an editable text field that allows the BlackBerry device user to type text in a field; in this example, they cantype their name. The application also includes a button field. When the BlackBerry device user types their name andclicks the Say Hello to button, the application displays a dialog box with the text Hello <username> as shown in thefollowing screenshot.

Create the Hello BlackBerry applicationBefore you begin: In the BlackBerry® Java® Plug-in for Eclipse®, make sure you turn on the BlackBerry ApplicationDevelopment perspective (Window > Open Perspective > Other > BlackBerry Application Development).

1. From the BlackBerry toolbar, click New BlackBerry Project.

2. In the Project name field, type HelloBlackBerry.

3. Select Create new project in workspace.

4. Select Use a project specific JRE.

5. Select BlackBerry JRE 7.0.0 from the drop-down list.

6. Click Next.

7. Click Next.

8. Select the Hello BlackBerry template.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

9

9. Click Finish.

In the Package Explorer pane, the HelloBlackBerry project appears. The project includes an src folder that containstwo Java® source files:• HelloBlackBerry.java: This file contains the source code for the main section of the application.• HelloBlackBerryScreen.java: This file contains the source code for generating the screen.

Running your BlackBerry Java applicationYou can run and test your application by using a BlackBerry® Smartphone Simulator or by using a BlackBerry device.

The BlackBerry® Java® Plug-in for Eclipse® includes simulators for various BlackBerry device models. The BlackBerrySmartphone Simulator runs the same Java® code as the BlackBerry devices, so the BlackBerry Smartphone Simulatorprovides an accurate environment for testing how your application functions on a BlackBerry device. When you testyour application, you should select a BlackBerry Smartphone Simulator that runs the BlackBerry® Device Softwareversion that corresponds to the BlackBerry® Java® SDK version that you choose to develop in. For example, if youare developing an application in BlackBerry Java SDK 6.0, select the BlackBerry SDK - 9800 simulator, which runsBlackBerry® 6. You can download other versions of the BlackBerry Smartphone Simulator from www.blackberry.com/developers/simulators.

You can also run your application on a BlackBerry device. You should verify that the BlackBerry Device Softwareversion on the device corresponds to the BlackBerry Java SDK that you are developing your application in.

If your application uses protected Research In Motion® APIs and you want to test on a BlackBerry device, you mustfirst get code signing keys from RIM. The BlackBerry® Java® Virtual Machine on the BlackBerry device is designed toprotect the underlying data and OS, so that applications cannot call undocumented APIs or unsupported APIs, oraccess data that is not exposed explicitly through the APIs. If a BlackBerry device application tries to access protectedRIM APIs, the BlackBerry Java Plug-in for Eclipse might display warning messages in the Java editor window or in theProblems view pane. The warning messages appear next to the lines of application code that reference a protectedAPI. You can suppress these warnings if you test your application on a non-secure device.

For more information about code signing and registering with RIM to use protected APIs, visit us.blackberry.com/developers/javaappdev/codekeys.jsp

Run your application on the BlackBerry Smartphone SimulatorIn the following steps, we'll use the Hello BlackBerry application that we created earlier to demonstrate how to runan application.

1. In the Package Explorer pane, select the project you want to run. For this example, select the HelloBlackBerryproject.

2. To run the application on the simulator, you can perform one of the following actions:• Right-click the project, and then select Run As > BlackBerry Simulator.• If you enabled the BlackBerry Application Development perspective, from the BlackBerry toolbar, click the

Run on BlackBerry Simulator button.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

10

The BlackBerry® Java® Plug-in for Eclipse® builds and packages the project, and then launches the BlackBerrySmartphone Simulator. By default, the BlackBerry Java Plug-in for Eclipse 1.3 uses the BlackBerry® Torch™ 9800simulator.

3. On the Home screen of the BlackBerry Smartphone Simulator, click the application icon. In this example, clickthe Hello BlackBerry icon.

The HelloBlackBerry application opens and displays a screen with an editable text field and a button.

4. To test the Hello BlackBerry application, type your name in the Enter Name field, and then click the Say Hello tobutton.A dialog box displays with the text Hello <your name> and an OK button. Click OK.

5. To close the application, on the simulator, press the Menu key, and then select Close.

6. To close the simulator, select File > Exit.

Run your application on a BlackBerry deviceBefore you begin: If your application uses protected Research In Motion® APIs, you must first get code signing keysfrom RIM. For more information about code signing and registering with RIM to use protected APIs, visitus.blackberry.com/developers/javaappdev/codekeys.jsp

1. Connect the BlackBerry® device to the computer by using a USB cable.Note: You can connect only one BlackBerry device at a time.

2. In the Package Explorer pane, right-click the project that you want to load on the device.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

11

3. Click BlackBerry > Load Project(s) on Device.The BlackBerry® Java® Plug-in for Eclipse® builds and packages the project. If the BlackBerry device is password-protected, you are promted to type the password. The application is loaded on to the device.

4. On the Home screen of the BlackBerry device, click the application icon to run the application.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

12

Introducing the Java SDK 4The BlackBerry® Java® SDK is divided into twelve categories. Each category consists of APIs that provide a separatetype of functionality, such as UI creation, networking, data storage, and security. All twelve categories are describedin the following sections.

Application lifecycle APIsThe lifecycle of an application refers to the possible states and transitions that an application can move through fromthe time it starts until it terminates. The lifecycle of a BlackBerry® application is straightforward: it starts, runs, andterminates. During the running state, most applications receive and process events and update their UI accordingly.

The BlackBerry operating environment is multi-threaded. It enables you to run multiple applications simultaneously.It supports broadcasting events to multiple applications and running background threads.

All applications have an application class derived from either Application or UiApplication. If you want an applicationwith a UI, then your application should extend UiApplication. Otherwise, your application should extendApplication.

A BlackBerry application can be started in a number of ways:

• A user clicks an icon on the home screen.• The system automatically starts the app when the smartphone starts.• Another application starts the app.• The system starts the app at a scheduled time.

Regardless of how an application is started, the Application Manager is responsible for starting the process that theapplication runs within. The ApplicationManager class enables applications to interact with the Application Managerto perform tasks, including:

• Run an application immediately or at a scheduled time.• Interact with processes, including retrieving the IDs for foreground applications.• Post global events to the system.

The Application Manager starts an application by getting a new process and spawning a thread within that processto call one of the entry points of the application. For many applications, the main() method of its application classis the single entry point that is called. However, you can configure more than one entry point for an application.Multple entry points allow users to start the app in different ways. For example, if your application allows users tocreate a new document, you might want to provide users with two icons that they can click to start the application.Users could click one icon to open the application in its home screen and the other icon to open the application inthe screen required to create a new document.

Application descriptors

Application descriptors are sets of data about an application. A single application can have more than one associatedapplication descriptor. An application that has multiple entry points has an application descriptor corresponding toeach of those entry points. You can use the ApplicationDescriptor class to work with application descriptors.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

13

The following code sample produces a list of the properties of applications.

import net.rim.device.api.system.ApplicationDescriptor;import net.rim.device.api.system.ApplicationManager;import net.rim.device.api.ui.UiApplication;import net.rim.device.api.ui.component.LabelField;import net.rim.device.api.ui.component.RichTextField;import net.rim.device.api.ui.container.MainScreen;

public class ListApplications extends UiApplication { StringBuffer strTmp = new StringBuffer(); public static void main(String[] Args) { ListApplications app = new ListApplications(); app.enterEventDispatcher(); } public ListApplications() { ApplicationManager appMgr = ApplicationManager.getApplicationManager(); ApplicationDescriptor[] ad = appMgr.getVisibleApplications(); for(int i=0;i<ad.length;i++) { strTmp.append("Name: "); strTmp.append(ad[i].getName()); strTmp.append('\n'); strTmp.append("Module Name: "); strTmp.append(ad[i].getModuleName()); strTmp.append('\n'); strTmp.append("Version: "); strTmp.append(ad[i].getVersion()); strTmp.append('\n'); strTmp.append('\n'); } this.pushScreen(new InfoScreen(strTmp.toString())); }}

class InfoScreen extends MainScreen{ public InfoScreen(String strMsg) { RichTextField lf = new RichTextField(strMsg); add(lf); }}

From that point on, the application is in an event processing loop. Any listeners you write and register, or are providedfor you by the application framework, are called by the event thread in response to corresponding incoming messages.

The event thread is the only thread that can process events and update the UI of the application, so you must notuse it to run instructions that could fail or take a long time to complete. If, for example, you need to make a networkconnection, you must spawn and use another thread.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

14

You may encounter situations where you want to update the UI from a non-event thread. There are two ways to dothat. You can acquire and synchronize the event lock, causing your thread to act like the event thread; or you caninject an event in the message queue of your application.

Synchronize on the event lock if you need to perform a quick or urgent UI update, or inject an event in the messagequeue if it is acceptable to experience a delay before your task runs. In either case, you should not run tasks thatmight take a long time to complete or might block. If you use library calls within your task, be sure you understandthem well and only use them if they will finish quickly and not block.

If you decide to synchronize on the event lock, you must quickly complete the UI update you require and release thelock. Otherwise, your application will become unresponsive and might eventually be terminated by the system. Youacquire the event lock by calling Application.getEventLock().

You inject an event in the form of an object that implements Runnable. The event is handled by the event thread asit is received from the message queue. The event thread processes the event by calling its run() method. To injectrunnable events in the message queue of your application, use the invokeAndWait() method or the invokeLater()method.

Terminating

One way to terminate an application is to invoke System.exit(), which causes the BlackBerry JVM to terminateall of the processes of the caller and, as a result, all associated threads. Alternatively, you can terminate an applicationby popping the last screen off the display stack, which causes the close() method to make a call to System.exit().

It is good practice to manually deregister any listeners you registered before terminating your application.

Because you will typically start the event dispatcher thread by calling Application.enterEventDispatcher(), whichdoesn't terminate, your application should provide a way to terminate. Applications that interact with the user couldprovide a handler for a Close menu item, and applications that do not interact with the user might terminate uponhandling some system event that represents their reason for existence.

UI APIThe UI API helps you create user interfaces for BlackBerry screens.

The three main UI objects are Screen, Manager, and Field. A screen is the top-level container for the UI elementsthat represent what you want to display. Screens can contain fields (such as text fields), radio buttons, and drop-down lists. Screens can also contain layout managers, which contain sets of fields. Layout managers are fieldsthemselves, so they can contain other managers. This architecture provides you with a lot of flexibility when designingyour UI.

Layout managers

The UI API provides a number of layout managers. The following layout managers are the most commonly used. Evenwith only these three types of managers, you can create rich layouts in your screens.

• VerticalFieldManager, which arranges fields in a single vertical column• HorizontalFieldManager, which arranges fields in a single horizontal row

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

15

• FlowFieldManager, which arranges fields first horizontally, then vertically

Fields

The UI API provides several prebuilt UI components that you can use to display particular types of data in a field.Following are some examples:

• ButtonField provides a simple button• LabelField provides a text label• TextField provides a text label• DateField allows you to store a date and display it in different formats in a field (such as 2011/11/17)• MapField allows you to render a map in a field• BrowserField allows you to display web content in a field

In addition to the useful field types that are defined in the UI API, you can create any type of field by extending theField class.

The following code sample creates a custom layout for a screen.

class MultiElementTextField extends Field { // Extend field. String[] _texts; // Array of text segments. int[] _spaces; // Array containing space allocated to each text segment. int_buffer; // Integer representing amount of buffer between text segments.

// Implement a constructor to set up data arrays and the buffer value. public MultiElementTextField(Object[] data, int buffer, long style) throws IllegalArgumentException { //Set up the particular style of field by calling super. super(style);

int n = data.length; if ((n % 2) != 0) { throw new IllegalArgumentException("Invalid number of elements"); } else { _texts = new String[n / 2]; _spaces = new int[n / 2]; } for (int i = 0; i < n ; i = i + 2) { _texts[i / 2] = (String)data[i]; _spaces[i / 2] = ((Integer)data[i+1]).intValue(); } _buffer = buffer; }

public boolean isFocusable()

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

16

{ // This field can accept the focus, return true. return true; }

// Use layout to determine the extent of the field. // Call setExtent(int, int) with the total field size. public void layout(int width, int height) { Font font = getFont(); int _fieldHeight = font.getHeight(); int _fieldWidth = 0; int n = _spaces.length; for (int i = 0; i < n; ++i) { _fieldWidth += _spaces[i]; if (i < n - 1) { _fieldWidth += _buffer; } } setExtent(_fieldWidth, _fieldHeight); }

// Use paint to draw text objects to the screen using the // Graphics object that is passed in. This example uses the values // from buffer and spaces[] to determine the location and // size of each segment of text. The ELLIPSIS style // replaces text that is too long for its allocated space // with three dots. public void paint(Graphics graphics) { int xpos = 0; int n = _spaces.length; for (int i = 0; i < n; ++i) { graphics.drawText(_texts[i],xpos,0,graphics.ELLIPSIS,_spaces[i]); xpos += _spaces[i]; if (i < n - 1) { xpos += _buffer; } } }}

Layout control

The UIe API includes layout managers that offer flexibility when displaying fields. You declare a layout manager atthe top level of your screen and then add fields to it. Because layout managers are subclasses of Field, they can beembedded in other layout managers. You can also define your own layout manager.

The following sample code creates a custom layout for a screen.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

17

class LayoutManager extends Manager { public LayoutManager() { // Construct a manager with vertical scrolling. super(Manager.VERTICAL_SCROLL); } // Overwrite the nextFocus method for custom navigation. protected int nextFocus(int direction, boolean alt) { // Retrieve the index of the field that is selected. int index= this.getFieldWithFocusIndex(); if(alt) { if(direction 0){...} else ...} } // If we did not handle it, let the manager's parent class. if (index == this.getFieldWithFocusIndex()) return super.nextFocus(direction, alt); else return index; }

protected void sublayout(int width, int height) { Field field; // Get total number of fields within this manager. int numberOfFields = getFieldCount(); int x = 0; int y = 0; for (int i = 0;i < numberOfFields;i++) { field = getField(i); // Get the field. setPositionChild(field,x,y); // Set the position for the field. layoutChild(field, width, height); // Lay out the field. y += ...; ... } setExtent(width, height); }

public int getPreferredWidth() { return 160; }

public int getPreferredHeight() { int height= 0; int numberOfFields= getFieldCount(); for (int i= 0; i < numberOfFields; i++) { height+= getField(i).getPreferredHeight(); return height;

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

18

} }

/**************** Main Class ****************/

... RichTextField myField = new RichTextField("Hello"); RichTextField myOtherField = new RichTextField("World"); LayoutManager myManager = new LayoutManager(); MainScreen myScreen = new MainScreen(); myScreen.add(myManager); myManager.add(myField); myManager.add(myOtherField);}

Screens

The UI API has two main types of Screen objects, PopupScreen and FullScreen. PopupScreen is subclassed by Dialog,Status, LocationPicker, and AbstractLocationPicker. FullScreen is subclassed by MainScreen and PhoneScreen.

You can display information that is supplementary to your application in a pop-up screen without interrupting theflow of the application. As a result, you do not have to leave the main screen and then return to it later. In addition,you can prioritize which PopupScreen objects are pushed to the top of the display stack by invokingpushGlobalScreen(Screen, int, int).

Menus

BlackBerry smartphones organize commands on a menu that can be accessed by pressing the Menu key. You canspecify the order of menu items and the menu item that is selected by default when the menu opens. In addition,you can add or remove menu items depending on the screen or application state when the menu displays.

Listeners

The UI API offers a flexible implementation of listeners that is based on a more complex organization of componentson a screen. The UI API contains a generic event listener model that permits you to implement listeners for manytypes of events, such as when a field is changed, or when the user presses a key, clicks the trackpad or trackball, ortouches the touch screen.

Model-View-Control design pattern

Some standard components in the UI API, including activity and progress indicators in thenet.rim.device.api.ui.component.progressindicator package and lists and tables in thenet.rim.device.api.ui.component.table package, use the Model-View-Controller (MVC) design pattern.

Before using these components, you should be familar with the MVC design pattern. There are many print and onlineresources where you can learn about MVC.

UI application threads

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

19

All UI applications that are written using the UI API contain one event dispatcher thread. The thread that invokesApplication.enterEventDispatcher() becomes the event dispatcher thread and starts to process events.

Using the event dispatcher thread

You can add a runnable object to the event queue. Create a class that implements the Runnable interface, and thenadd the Runnable object to the event queue by using one of the following methods (which are located in thenet.rim.device.api.system.Application package):

• Use invokeAndWait(Runnable runnable) to queue the Runnable object to be called on the event dispatcherthread. This method blocks and does not return until the run() method returns.

• Use invokeLater(Runnable runnable) to queue the Runnable object to be called on the event dispatcher threadafter all pending events are processed. This method returns immediately, instead of blocking until run() returns.

• Use invokeLater(Runnable runnable, long time, Boolean repeat) to queue the Runnable object to be called onthe event dispatcher thread after a specified amount of time. This method returns immediately, instead ofblocking until run() returns. The time parameter specifies the number of milliseconds to wait before addingthe Runnable object to the event queue. If repeat is true, the Runnable object is added to the event queueevery time milliseconds.

Any thread can modify a Screen object before it is pushed on to the display stack or after it is popped off of the displaystack.

The following code sample updates a screen on the event thread by calling invokeLater(Runnable runnable).

UiApplication.getUiApplication().invokeLater (new Runnable() { public void run() { //Perform screen changes here.

//Calling invalidate() on your screen forces the paint method to be called. screenName.invalidate(); }});

Using a background thread with the event lock

You can use background threads to access the UI by acquiring the event lock for a short time. InvokeApplication.getEventLock() on the background thread to retrieve the event lock, and then synchronize this object toserialize access to the UI. You should only hold this lock for short periods of time because it pauses the event dispatcherthread. An application should never call notify() or wait() while holding the event lock on the background thread.

Modal screens

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

20

Screen objects are pushed on to the display stack by the pushScreen() and pushModalScreen() methods of theUiApplication class. Because pushModalScreen() blocks until the screen is popped off the display stack (wherepushScreen() returns immediately), the order of operations is crucial when you use modal screens. Do not invokepushModalScreen() before starting the event dispatcher thread; doing so throws a RuntimeException. Othermethods, such as Dialog.inform() and Dialog.alert(), also use pushModalScreen().

Graphics

You have several options for creating graphics on a BlackBerry smartphone:

• You can add predefined UI components such as text, input controls, and images to Screen objects.• You can do simple custom drawing on a screen by overriding the paint() method of the class that represents

the screen and using the methods supplied by the Graphics object to draw on the screen.• You can draw 2D graphics with the SVG APIs: org.w3c.dom, org.w3c.dom.events, and org.w3c.dom.svg.• You can make more sophisticated 2D images using the Graphics Utility API: OpenGL ES API or OpenVG API.• You can create 3D images using the OpenGL ES API.

More information about the user interface• BlackBerry Java SDK UI Component Development Guide• BlackBerry Java SDK UI and Navigation Development Guide• BlackBerry Java SDK UI Design Guidelines• BlackBerry Java SDK Graphics and Animation Development Guide

Application integration APIsThe Application integration APIs contain packages you can use to integrate your apps with core applications such asthe Contacts application, the Phone application, and the Media application.

Invoke API

You can use the Invoke API to invoke core applications and optionally pass in data. To use this API, callinvokeApplication and pass in the application type and any relevant arguments. You can use the Invoke API to invokethe following core applications:

• contacts• calculator• calendar• camera• BlackBerry Maps• memos• messages• phone• search• tasks

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

21

Invoke contains APP_TYPE fields that enumerate the applications.

For each core application that can be invoked with the Invoke API, there is a corresponding subclass of theApplicationArguments class. For example, to invoke the Phone application, call invokeApplication and pass in thePhone application type and a PhoneArguments argument. To invoke an application with no arguments, pass in nullinstead of an ApplicationArguments object.

Content Handler API

You can use the Content Handler API (CHAPI) to invoke both core applications and third-party applications. JSR 211defines CHAPI as a Java ME optional API. For more information about CHAPI, see the javax.microedition.contentpackage overview.

To use CHAPI to invoke applications, provide a URL, a content type, or a content ID with one of the constructors inthe javax.microedition.content.Invocation class. When you use CHAPI with the RIM provided content IDs for invokingRIM content handlers, CHAPI can be a good way to set invocation parameters for core applications, including theMedia application. You can also use CHAPI to invoke third-party apps that register as content handlers.

The following code sample starts the Media application to view the picture library using CHAPI.

Registry registry = Registry.getRegistry(MyApplication.class.getName());Invocation invocation = new Invocation(null, null, BlackBerryContentHandler.ID_MEDIA_CONTENT_HANDLER, false, ContentHandler.ACTION_OPEN); invocation.setArgs(new String[] {BlackBerryContentHandler.MEDIA_ARGUMENT_VIEW_PICTURES}); registry.invoke(invocation);

BlackBerry Browser

You can invoke the BlackBerry Browser and open a web page with the methods in the Browser class and theBrowserSession class. For example:

BrowserSession bSession = Browser.getDefaultSession();bSession.displayPage("http://www.blackberry.com");

For more information about invoking a browser, including how to invoke a browser that is not specified as the defaultbrowser, see the Knowledge Base article Invoke the browser.

You can also embed web content in your application with the BrowserField class.

Application Manager

You can start a core application with the ApplicationManager class, specifying the code module of the application.Use this technique only if the application cannot be invoked with any of the techniques described above. You cannotpass application arguments to a core application with this technique. You can use ApplicationManager to invokethe following core applications:

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

22

Application Module name

clock net_rim_bb_clocksounds net_rim_bb_profiles_appBlackBerryMessenger

net_rim_bb+_qm_peer

options net_rim_bb_options_app

Note: The module names for core applications are subject to change. Invoking modules directly can have unintendedside-effects.

Enabling core applications to invoke your application

You can add menu items to a core application with the menuitem package. For example, you can add a menu itemcalled View Sales Order to the Contacts application. When the user clicks View Sales Order, your application opensand displays a list of sales orders for that contact.

The ApplicationMenuItemRepository class provides the constants that specify the core application that your menuitem appears in. For example, the MENUITEM_MESSAGE_LIST constant specifies that the menu item appears in theMessages application. The MENUITEM_SYSTEM constant specifies that your menu item appears in most coreapplications.

The following code sample creates and registers a menu item using the ApplicationMenuItemRepository.

// Create a menu item.int placement = 0x350100;ApplicationMenuItem ami = new ApplicationMenuItem(placement) { public Object run(Object context) { // do something return null; } public String toString() { return "My menu item"; }};

// Register the menu item.ApplicationMenuItemRepository amir = ApplicationMenuItemRepository.getInstance();

amir.addMenuItem(ApplicationMenuItemRepository.MENUITEM_SYSTEM, ami, ad_menuhandler); // ad_menuhandler is an ApplicationDescriptor

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

23

The applications that use the ActiveAutoTextEditField or the ActiveRichTextField field (for example, the Calendar andMessages applications) can recognize string patterns and provide specific items for those string patterns in the menuon the smartphone. For example, if a message contains a phone number, the number is highlighted. If the smartphoneuser selects the number and presses the Menu key, the special menu item Call Number displays.

You can define your own string patterns and associate the patterns with custom menu items. The custom menu itemsdisplay when a user selects a matching string in an ActiveAutoTextEditField or ActiveRichTextField fieldand opens the menu. The custom menu items can perform any action, such as starting your application.

You can use the PatternRepository class to register a Perl-style regular expression or a specific string with the patternrepository on the smartphone. You can use the ApplicationMenuItem class to define a menu item that is associatedwith the string pattern.

For example, the following code sample registers a string pattern and a menu item:

String pattern = “[Bb]lack[Bb]erry [Ss]martphone";

int patternType = PatternRepository.PATTERN_TYPE_REGULAR_EXPRESSION;PatternRepository.addPattern(ad_menuhandler, pattern, patternType, new ApplicationMenuItem[] { ami });

For more information about PatternRepository and active text fields, see Active Text Fields sample application.

You can register the content handlers that invoke your application by using the Registry class, which is provided inthe Content Handler API. When you register a content handler, you can provide an array to specify the actions thatinvoke the handler. ContentHandler.ACTION_OPEN content handlers for the MIME types that are not supportedby the smartphone are used in the BlackBerry Browser, file explorer, and in the Open Attachment menu item in theMessages application. ContentHandler.ACTION_SEND content handlers for the image or video MIME types areused in the file explorer (including in the Media application) and in the Send As menu in the Camera application.

The following code sample registers a content handler:

private static void registerApp(){ try { // This application is a handler for csv files // and will be invoked with ACTION_OPEN. String[] types = {"text/csv"}; String[] suffixes = {".csv"}; String[] actions = {ContentHandler.ACTION_OPEN}; // Get access to the registry and register as a content handler. // CLASSNAME is the fully qualified name of the application. Registry registry = Registry.getRegistry(CLASSNAME); registry.register(CLASSNAME,types,suffixes,actions,null,ID,null); } catch (ContentHandlerException che) { errorDialog("Registry#register() threw " + che.toString());

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

24

} catch (ClassNotFoundException cnfe) { errorDialog("Registry#register() threw " + cnfe.toString()); }}

The following code sample invokes a content handler:

private static final String URL = "file:///SDCard/rim.csv"; private void doInvoke(){ try { // Create the Invocation with the hard-coded URL. Invocation invoc = new Invocation(URL); invoc.setResponseRequired(false); // We don't require a response. // We want to invoke a handler that has registered with ACTION_OPEN. invoc.setAction(ContentHandler.ACTION_OPEN); // Get access to the Registry and pass it the Invocation. // CLASSNAME is the fully qualified name of the application. Registry registry = Registry.getRegistry(CLASSNAME); registry.invoke(invoc); } catch (IOException ioe) { errorDialog("Registry#invoke() threw " + ioe.toString()); }}

Embedding content in BlackBerry applications

You can embed content in applications in several ways, including the following:

• Add applications to the Messages application using the messagelist package• Link contacts in your application with contacts in the Contacts application using the contactlinking package• Add content to phone screens using the phonequi pacakge• Add options for your application using the options package• Register your application as a notification source using the notification package

Embedding UI components in your application

You can include in your applications many specialized UI components. For example, you can implement:

• Autocomplete fields using the component package• Location pickers (which allow users to select a location using such means as contacts, GPS, recent locations, and

suggestions from your app) using the picker package in the LBS API• File pickers (which allow users to select a file from a folder) using the picker package in the UI API• Embedded maps using the MapField class

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

25

• Embedded web content using the BrowserField class• Embedded media players and media recorders using the Mobile Media API (JSR 135), as implemented in

javax.microedition.media and javax.microedition.media.control

More information about application integration• BlackBerry Super Apps• BlackBerry Java SDK Super App Development Guide• BlackBerry Java SDK Integration Development Guide• BlackBerry Java SDK UI and Navigation Development Guide

PIM APIsThe PIM APIs include packages that allow you to access address books, calendars, tasks, and memopads from yourapplication. The BlackBerry® smartphone fully supports the J2ME PIM implementation established in JSR 75, andprovides a number of custom extensions.

The javax.microedition.pim package provides a number of interfaces that allow you to access PIM data on a BlackBerrysmartphone. PIM data is organized into PIM lists, items, and fields. PIM lists are databases that contain all PIM itemsthat can be accessed on a smartphone. PIM lists maintain categories, which are logical groupings for the PIM itemscontained in the list. Each PIMList object can support zero or more categories. Categories are represented by uniqueString names.

A PIMItem object represents a collection of data for a single PIM entry. A PIMItem is a grouping of related fields,with each field consisting of a label, a data type, value(s), and attribute(s). A PIM item is created from a particularPIM list and is associated with that list for the life of the item. A PIM item can have its data imported and exportedusing standard byte-based formats. Each implementing class defines what formats can be imported and exportedfor that item.

You can launch PIM applications with the BlackBerry Invoke API.

RIM extensions

RIM extensions to J2ME PIM include:

• Support for multiple calendars, multiple calendar lists, and contact lists• Reading and writing to MemoPad• Getting and setting recurrence for ToDo items• Setting a standard UI for selecting a contact• Global Address List (GAL) lookups (for BlackBerry Enterprise Server environments)

For more information about RIM extensions to PIM, see net.rim.blackberry.api.pdap.

More information about PIM• BlackBerry Java SDK Integration Development Guide• PIM API category overview

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

26

Messaging APIsThe Messaging APIs allow you to use messaging functionality in your apps, including emails, application messages,SMS, MMS, and BBM.

Email messages

The packages for email messages are net.rim.blackberry.api.mail and net.rim.blackberry.api.mail.event.

To create and send email messages, you set the default Session, retrieve a Store instance, create the email message,and store the email in a retrieved sent folder. Finally, you set up and send the email message.

The following sample code creates and sends a text email message.

// Get the Store from the default mail Session. Store store = Session.getDefaultInstance().getStore(); // Retrieve the sent folder. Folder[] folders = store.list(Folder.SENT); Folder sentfolder = folders[0]; // Create a new message and store it in the sent folder.Message msg = new Message(sentfolder); Address recipients[] = new Address[1]; try { recipients[0]= new Address("user@company.com", "user"); //Add the recipient list to the message. msg.addRecipients(Message.RecipientType.TO, recipients); //Set a subject for the message. msg.setSubject(“Test email”); //Set the body of the message. msg.setContent("This is a test email from my BlackBerry device"); //Set priority. msg.setPriority(Message.Priority.HIGH); //Send the message. Transport.send(msg); } catch (Exception me) { System.err.printIn(me); }

Application messages

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

27

You can use the messagelist package to create application messages. An ApplicationMessage is a custom messagethat appears in the Messages application and invokes your application when the user opens it or chooses a menuitem that you provide for the message.

SMS and MMS messages

You can create applications that send and receive SMS messages or MMS messages. SMS support is provided throughJSR 120. MMS support is provided through JSR 205. You can perform the following actions:

• Send and receive SMS messages• Send and receive MMS messages• Configure listeners for outgoing and sent messages

You can send SMS messages with the javax.wireless.messaging API and the BlackBerry® Invoke API. You can't sendSMS messages directly from a BlackBerry smartphone that operates on a CDMA network.

To receive SMS messages using BlackBerry Java SDK 4.6.0 or later, use the MessageListener interface. If you are usingan earlier version of the SDK, use the MessageConnection interface.

If you want specific SMS messages to be saved in an SMS message folder, you must specify the folder location usingMessageArguments when the SMS message is received by the BlackBerry smartphone. Applications cannot accessSMS messages that are stored on the BlackBerry smartphone.

To listen for incoming SMS messages that appear in the message list, set the port number argument inConnector.open() to 0 - Connector.open("sms://:0").

MMS messages consist of an MMS header and body. The MMS header consists of address, priority, subject, anddelivery information. The MMS body contains the multimedia attachment portion.

Sending MMS messages is similar to sending SMS messages, except that you must pass in the MULTIPART_MESSAGEconstant when creating the MessageConnection object.

To receive MMS messages when using the BlackBerry Java SDK 4.6.0 or later, use the MessageListener interface. Ifyou are using an earlier version of the BlackBerry JDE, use the MessageConnection interface.

To listen for incoming MMS messages that appear in the message list, set the selected Connector.open() applicationID to 0.

In addition to providing notification to applications when messages are received (using the MessageListenerinterface), you can also configure application notification for outgoing and sent SMS messages and MMS messages.For SMS messages, you can configure your application to track sent SMS messages by passing an instance of a classthat implements the OutboundMessageListener interface when invokingMessageConnection.setMessageListener(). Notification using this interface occurs only after the message is sentsuccessfully. If the send operation fails, the application is not notified.

BlackBerry Messenger

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

28

BlackBerry® Messenger is an instant messaging program that lets BlackBerry smartphone users communicate witheach other. BBM is unique among mobile instant messaging applications in that users do not need to sign into or outof the application. As long as smartphones are connected to a wireless network, BBM can keep users connected totheir BBM contacts and groups.

The BlackBerry Messenger SDK is a separate download from the BlackBerry Java SDK. The BBM SDK, used inconjunction with the BlackBerry Java SDK, lets you develop applications that incorporate social features such as peer-to-peer connections between BlackBerry smartphones and integrated chats. For example, in a chess gameapplication, a BlackBerry smartphone user could invite a BBM contact to play a game of chess, and the moves couldbe communicated back and forth using the BBM platform. There is no need to develop these social features yourself,and no server-side development is required to support them.

For more information about BBM, see the BlackBerry Messenger Social Platform SDK developer guides.

More information about messaging• BlackBerry Java SDK Integration Development Guide

Network Connection APIsThe Network Connection APIs contain packages to manage input and output data streams. The APIs provide a widerange of functionality. You can use them to connect and work with everything from a microSD form factor smart cardto an enterprise LDAP service. You can also use the Generic Connection Framework (GCF).

A BlackBerry® smartphone uses radio communication technologies such as Wi-Fi® technology, CDMA, and GPRS tocommunicate over wireless connections. BlackBerry smartphones work with different network transport methodsover those radio technologies to connect to the Internet or private networks.

Network API

The Network API is designed to make it easy to create HTTP, HTTPS, Socket, TLS, SSL, UDP, and Datagram connections.It includes classes for the two main tasks involved in creating a network connection:

• probe: TransportInfo class• connect: ConnectionFactory class

You can use the TransportInfo.getAvailableTransportTypes() method to determine which transport types aresupported by a smartphone. You can then use the TransportInfo.isTransportAvailable() method to determinewhether the smartphone is currently capable of using the supplied transport type. Finally, you can test the coverageof the transport type by using TransportInfo.hasSufficientCoverage(). After that sequence of probing calls, you knowwhat transports are available and whether the smartphone is in coverage for your transport of choice.

The Network API does not make connection creation thread-safe. Your application will lock if you callConnectionFactory.getConnection() on the event thread. When calling this method to create a connection, create anon-event thread.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

29

The simplest way to use the ConnectionFactory class to create a connection is to call theConnectionFactory.getConnection() method, specifying only the URL to connect to. The method will return aConnectionDescriptor object from which you can call ConnectionDescriptor.getConnection() to retrieve a Connectionobject that you can cast to an appropriate subobject.

The BlackBerry solution also enables server-side applications to proactively push data to BlackBerry smartphones ina secure and reliable manner.

Generic Connection Framework (GCF)

The GCF is an easy-to-use, extensible framework that lets you create connections and perform input and outputoperations. It is provided in javax.microedition.io and java.io.

Every connection you make using the GCF starts with the connection factory, which is implemented by the Connectorclass. You call Connector.open() to create any type of supported connection. The first parameter toConnector.open() is a URI (as described in RFC 2396) that specifies the type of connection to make, the endpointto connect to, and optional connection configuration details. When the connection is established, a connectioninterface that corresponds to the type of connection that was created is returned from the call toConnector.open(). You cast the returned connection interface to the appropriate connection subtype accordingto the URI you specified.

Other types of connection• LDAP: net.rim.device.api.ldap• Push service: Push Service development guides• Smart cards and smart card readers: net.rim.device.api.smartcard• Javacards: javax.microedition.jcrmi

More information about network connections• Network Connections category overview• BlackBerry Java SDK Networking and Connectivity Development Guide• Network Transports Tutorial• Push Service development guides

CLDC Platform and Utilities APIsThe CLDC Platform and Utilities APIs provide core language functionality for your applications. The packages are:

• CLDC 1.1 core packages• J2ME web server packages• RIM packages that are extensions to CLDC and J2ME

CLDC 1.1 core packages

These packages are part of JSR 139, Connected Limited Device Configuration version 1.1. These packages providethe core set of APIs for developing applications on resource-constrained wireless devices, such as BlackBerry®smartphones.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

30

• java.lang provides the core Java classes• java.lang.ref provides support for weak references (references that do not protect objects from garbage

collection)• java.util provides the standard collection classes (Hashtable, Stack, and Vector) and date/time support

J2ME Web Services packages

These packages are part of JSR 172, the J2ME Web Services Specification. These packages provide basic support forJava ME devices, such as a BlackBerry smartphone, to act as a web service client using standard programminginterfaces.

• java.rmi provides the core Remote Method Invocation classes• javax.microedition.xml.rpc provides JAX-RPC support• javax.xml.namespace provides namespace support• javax.xml.parsers provides support for processing XML documents by using SAX (Simple API for XML) event-

based XML processing• javax.xml.rpc provides JAX-RPC support on the web service client• org.xml.sax provides core SAX support• org.xml.sax.helpers provides helper classes for SAX support

RIM extension packages

RIM provides APIs that complement Java Community Process APIs.

Applications that use the RIM provided APIs are not portable to devices that are not BlackBerry devices. If portabilityto other types of devices is important to you, use only the standard Java ME packages. Otherwise, consider takingadvantage of the optimizations and specializations available in the RIM provided packages. For example, you can useRIM provided collection classes, such as BigVector or UnsortedReadableList, instead of the standard Vector class.

In some cases, RIM provides classes that exist in Java SE but are not provided (or only partially provided) in standardJava ME. For example:

• net.rim.device.api.xml.parsers supplements javax.xml.parsers by adding DocumentBuilder andDocumentBuilderFactory, classes available in Java SE but not in standard Java ME

• net.rim.device.api.util.Arrays provides much of the functionality of Java SE's Arrays class, which is not availablein standard Java ME

• net.rim.device.api.util.MathUtilities contains methods that are available in Java SE's java.lang.Math class,but not in standard Java ME, including inverse trigonometric methods

• net.rim.device.api.xml provides constants for use in processing WBXML, which is a binary form of XML suitablefor use in wireless applications.

• net.rim.device.api.xml.jaxp package provides support for XML processing and supplements org.xml.sax byadding extensions to the standard helper classes

The RIM provided packages in the CLDC Platform and Utilities category are:

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

31

• Web-service and XML-related packages: net.rim.device.api.xml, net.rim.device.api.xml.jaxp, andnet.rim.device.api.xml.parsers

• Collections-related packages: net.rim.device.api.collection, net.rim.device.api.collection.util, andnet.rim.device.api.util

• Math and other utilities: net.rim.device.api.math and net.rim.device.api.util

More information about the CLDC category and utilities• J2ME Web Services (Sun white paper)

Device characteristics and BlackBerry infrastructurecategoryThe packages in this category include classes that let you query for details about the hardware and othercharacteristics of a BlackBerry® smartphone.

Device characteristics

There are some general mechanisms you can use to query information about a smartphone.

You can use System.getProperty() to get information about many smartphone characteristics, including whether thedevice supports audio mixing and what time zone is currently set on the device.

Beginning with BlackBerry Java SDK 6.0, you can use the DeviceCapability class to query information about asmartphone. The class indicates whether covered capabilites are supported, allowed, or available.

The following classes, mostly in the net.rim.device.api.system package, provide methods to obtain information abouta device:

• AccelerometerSensor• Audio• Backlight• BluetoothSerialPort• Branding• CDMAInfo• DeviceInfo• Display• GPRSInfo• GPSInfo• LED• Memory• OwnerInfo• RadioInfo• Sensor• SIMCardInfo

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

32

• USBPort

BlackBerry infrastructure

BlackBerry infrastructure includes the BlackBerry Enterprise Server (including IT policies and application controlpolicies) and the BlackBerry Internet Service. In the BlackBerry Java SDK, infrastructure includes the followingpackages:

• Push Service: net.rim.blackberry.api.push provides an efficient and reliable way of sending information to yourusers, as well as a way to let your application process information in the background and notify users when theirattention is required.

• Service book: net.rim.device.api.servicebook allows your application to interact with the service book. Forexample, you can use a service record to keep of multiple email connections or to search for individual emailswithin an email hierarchy based on the email item's content ID.

More information about device characteristics and BlackBerry infrastructure• Device Characteristics and BlackBerry Infrastructure category overview• BlackBerry Enterprise Server

Data storage APIsThere are several ways you can store, share, and manage data for your apps:

Data storage approach Description and API

File system Store data in files and folders using the FileConnection API.SQLite® database Store data in relational databases using the Database API.Persistent store Save objects across smartphone restarts using the PersistentStore API.Runtime store Save objects nonpersistently, which is useful for sharing data between applications and

creating system-wide singletons, using the RuntimeStore API.Record store Store data in the MIDP Record Management System using the RMS API.

The following table compares the features of each approach:

Features File system SQLitedatabase

Persistent store Runtime store Record store

Data format Any Relationaldatabase file

Java® object Java object Serialized

Storage locations Applicationstorage,external mediacard, built-inmedia storage

Externalmedia card,built-inmediastorage

Applicationstorage

Applicationstorage

Applicationstorage

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

33

Features File system SQLitedatabase

Persistent store Runtime store Record store

Maximum storagelimit

Size ofpartitions theuser has accessto

Size ofpartitionsthe user hasaccess to

Availableapplicationstorage

Availableapplicationstorage

Differsaccording toBlackBerry®Device Softwareversion

BlackBerry DeviceSoftware support

4.2 or later(FileConnectionAPI)

5.0 or later All 3.6 or later All

Persists acrosssmartphone restarts

Yes Yes Yes No Yes

Applications can sharedata

Yes Yes Yes Yes Yes

Following are some considerations for choosing a data storage approach:

• The file system and SQLite databases are typically the most efficient storage location for large, read-only filessuch as videos or large graphics.

• Memory on wireless smartphones can be very limited, so you should consider not storing all data on thesmartphone. BlackBerry® smartphones are frequently connected so your application can access data whenneeded. In many cases, the best approach is to store data across smartphone restarts only for data that isfrequently accessed.

• When you consider where to store essential data, keep in mind that microSD cards can be removed.• There is more latency in writing to application storage than there is in reading from it. For example, reading

from the persistent store is relatively fast while commits are relatively slow.• The file system and record store are standards-based approaches, while the persistent store and runtime store

are specific to BlackBerry smartphones. If you want your application to run on other Java® ME compatibledevices, you should consider a standards-based approach.

More information about data storage• BlackBerry Java SDK Data Storage Development Guide

Multimedia APIThe Multimedia API allows you to play and record audio and video. This API is the the MIDP 2.0 Media API, providedin the javax.microedition.media package.

To record and play media in your app, use the Player class. To create an instance of a Player class, invoke createPlayer()in the javax.microedition.media.Manager class.

When the Player is first created using one of the createPlayer() methods, it is in an UNREALIZED state. Beforeyou can have access to the associated metadata or controls for the Player, you must invoke the Player object's realize()method. This method transitions the Player to a REALIZED state.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

34

In the REALIZED state, the Player class provides access to associated resources that control playback and recording.You can use the Player object's getControl() and getControls() methods (inherited from Controllable), passing in aString specifying the Control object that you require. You can find the available controls for your media player inthe javax.microedition.media.control package.

Before your application closes, you must invoke the Player object's close() method to deallocate any resources thePlayer has created. You can also do this at any time to free up memory or resources. After you invoke close(), youcan no longer use the Player.

More information about multimedia• Multimedia category overview• BlackBerry Java SDK Multimedia Developoment Guide

Location-Based Services APIYou can use the packages in the LBS API to:

• Find a location• Display information in a map• Estimate the time and distance of a trip• Perform geofencing (mark an area to monitor so that you fire events when someone enters the area)

Finding a location

You can retrieve location information for a BlackBerry® smartphone by using one of the following services:

• GPS: Provides location information using GPS satellites. You can retrieve GPS location information using the JSR179 Location API in the javax.microedition.location package or the BlackBerry extensions to JSR 179 in thenet.rim.device.api.gps package.

• Geolocation: Provides location information using cell tower positioning and WLAN access points. You do notrequire GPS technology on the smartphone to use the geolocation service. Geolocation is useful for applicationsthat require an approximate location and that can be used indoors (for example, applications that recommendlocal points of interest). You can retrieve geolocation using the net.rim.device.api.gps package.

• Geocoding and reverse geocoding: Provides geospatial coordinates for a street address (geocoding), andprovides a street address for geospatial coordinates (reverse geocoding).

Displaying information in a map

After you retrieve the location for a BlackBerry smartphone, you can display the location information in BlackBerry®Maps or custom maps.

BlackBerry Maps is a map and location application that can display a map, the location of the BlackBerry smartphone,a route from a starting location to a specific ending location, and points of interest on a map.

To create custom maps, you can add a MapField or RichMapField object to a screen, just as you add other UIcomponents. Once you have a custom map, you can use it in any of the following ways:

• Specify locations on the map

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

35

• Control the behavior of the map• Create custom shapes and objects, and display them• Display mappable objects that can be updated dynamically as information changes• Add fields and overlays to the map• Customize the look and feel of the map

Your application can interact with BlackBerry Maps in the following ways:

• Invoke BlackBerry Maps from your application using the Invoke.invokeApplication() method withMapsArguments parameters. You can display the following:• a location for an address in the Contacts application• a location for a landmark• a location at specific coordinates• a location or route by using a location document• a locations by using local search information• a KML overlay

• Open BlackBerry Maps from the BlackBerry Browser

You can create a location picker dialog box that allows a user to choose a location from a list of available selectionsthat you define. You can define the location picker dialog box with the Location Picker API, which is provided in thenet.rim.device.api.lbs.picker package. The location is passed using a javax.microedition.location.Landmark object.

Estimating the time and distance of a trip

You can retrieve the estimated time and distance it takes to travel between two points on a given date and at a giventime using the Travel Time API. Currently, the Travel Time API provides estimates only for automobile travel in theUnited States and Canada.

To request a travel time estimate, retrieve an instance of the TravelTimeEstimator class. Use therequestArrivalEstimate() method and specify the coordinates for the starting and ending locations, and the startingtime. The request is forwarded to a Travel Time server, which identifies a route between the starting and endinglocations and uses live and historical traffic information to calculate a travel time estimate. The estimate reflects theknown conditions on the specified date and at the specified time. The travel time estimate is returned by theTravelTimeEstimator using an instance of the TravelTime class.

Performing geofencing

You can use the Geofence class that is provided in the net.rim.device.api.location package to define geofenced areasand receive notifications when a BlackBerry smartphone user enters or leaves the specified area. A geofence is avirtual geographic area of interest that you can define by a radius around a location, or by coordinates that define apolygon for the location.

Your application must instantiate a Geofence object and implement the GeofenceListener to receive notificationsfor geofencing events (when a user enters or exits geofenced areas). Each instance of Geofence can process up to20 monitored areas concurrently.

More information about LBS

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

36

• Location-Based Services category overview• BlackBerry Java SDK Location-Based Services Development Guide

Security APIsThe Security APIs include the RIM® Cryptographic API and Content Protection.

RIM Cryptographic API

Using the RIM Cryptographic API, you can encrypt and decrypt data, digitally sign and verify data, work with highlysecure connections, and manage cryptographic keys.

Secure Messaging API: The Secure Messaging API is an implementation of the CMS standard. CMS specifies standardcontent types for cryptography. It describes message and transmission formats for those content types. S/MIME isbuilt on CMS. The net.rim.device.api.crypto.cms package provides classes to help you create and manageCMS content types.

Secure Connection API: The Secure Connection API defines protocol functionality that you can use to establish highlysecure communication. You can use the following protocols:

• SSL: SSL is designed to secure data that is sent over TCP/IP connections; it is used in the implementation ofHTTPS. SSL is provided in the net.rim.device.api.crypto.tls.ssl30 package.

• TLS: TLS is a standard from the IETF that is based on SSL version 3. TLS was designed to replace SSL and has beenwidely adopted. TLS is provided in the net.rim.device.api.crypto.tls package and thenet.rim.device.api.crypto.tls.tls10 package.

• WTLS: WTLS is a layer on top of WAP rather than TCP/IP. Securing wireless communications that use WAPinvolves using WTLS between the client smartphone and the WAP gateway, and one of SSL or TLS beyond theWAP gateway. WTLS is provided in the net.rim.device.api.crypto.tls.wtls20 package.

Keystore API: A key store is a database that stores cryptographic keys and certificates. Each BlackBerry® smartphonehas a key store that is preloaded with root certificates for all of the certificate authorities. This practice makes itpossible for BlackBerry smartphone users to trust the root certificates, which form the basis for all subsequent chainsof trust. Key store classes are provided in the net.rim.device.api.crypto.keystore package.

Certificate API: Certificates are electronic documents that hold keys, along with identifying information. There areseveral packages to help you manage cryptographic certificates:

• net.rim.device.api.crypto.certificate• net.rim.device.api.crypto.certificate.status• net.rim.device.api.crypto.certificate.x509• javax.microedition.pki• net.rim.device.api.crypto.certificate.wtls

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

37

Encoder API: Encoding is the process of converting data from one format to another. While it is often part of theencryption process, encoding is not the same as encryption and is generally not secure. Keys are encoded to providea standard representation, not to protect their identity. Classes for encoding keys and signatures are provided in thenet.rim.device.api.crypto.encoder package.

ASN1 API: Most applications use certificates that are produced by a certificate authority. If you need to parse or readcertificates yourself, you must use the net.rim.device.api.crypto.asn1 package.

OID API: Object identifiers are managed with the net.rim.device.api.crypto.oid package.

Primitives API: Cryptographic primitives are the keys, MACs, ciphers, unkeyed algorithms such as digests and PRNGs,and other functionality associated with both symmetric and public key cryptography. Cryptographic primitives areprovided in the net.rim.device.api.crypto package.

Content Protection

Content protection addresses the problem of someone stealing a smartphone and copying its data, which may bepossible even when data is encrypted and the smartphone is locked. Content protection encrypts data in such a waythat the encryption key is inaccessible when the smartphone is locked.

There are three parts to a content protection implementation:

• There is content protection functionality on every BlackBerry smartphone. To use it, the smartphone must havea device password, and content protection must be enabled by the smartphone user or by an IT policy rule.

• To protect data in an application, the application must subscribe to the content protection framework byregistering a listener.

• Content protection functionality is triggered by the user locking and unlocking the smartphone.

Content protection can be used to encrypt data in String objects or byte arrays. Content protection can apply to datathat is not persisted, but the Content Protection API contains specific functionality for the persistent store.

The following classes and interfaces are used to implement content protection:

• net.rim.device.api.system.PersistentContent: This class contains utility methods for encoding and decodingdata, registering listeners, and performing other tasks related to content protection.

• net.rim.device.api.system.PersistentContentListener: This listener interface lets your application receivenotifications when there are changes toa smartphone's content protection state or content protection settings.

• net.rim.device.api.system.PersistentContentException: This exception is thrown when an error occurs withcontent protection.

More information about security• BlackBerry Java SDK Security Development Guide• Cryptography category overview

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

38

Support for standard Java APIsThe BlackBerry® Java® SDK includes Java® ME APIs as well as BlackBerry-specific APIs. Here is a list of the supportedJSRs:

• JSR 30: Connected Limited Device Configuration (CLDC) version 1.0 (supported on devices with BlackBerry®Device Software version 4.6.1 or earlier)

• JSR 37: Mobile Information Device Profile (MIDP) version 1.0• JSR 75: Portable Optional Packages for the J2ME Platform (PDAP) support for the PIM APIs and the File Connection

API for Java ME• JSR 82: Java APIs for Bluetooth®• JSR 118: Mobile Information Device Profile (MIDP) version 2.1• JSR 120: Wireless Messaging API (WMA) Version 1.1• JSR 135: Mobile Media APIs (MM API) Version 1.1• JSR 139: Connected Limited Device Configuration (CLDC) version 1.1• JSR 172: J2ME Web Services• JSR 177: Security and Trust Services API for J2ME (SATSA-APDU)• JSR 179: Location API for Java ME• JSR 185: Java Technology for the Wireless Industry (JTWI)• JSR 205: Wireless Messaging API 2.0 (WMA)• JSR 211: Content Handler API (CHAPI)• JSR 226: Scalable 2D Vector Graphics API for Java ME (SVG)• JSR 234: Advanced Multimedia Supplements (AMMS)• JSR 238: Mobile Internationalization API• JSR 239: Java Bindings for the OpenGL® ES API (on some devices)

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

39

Find more information 5For more information about BlackBerry® application development, see the following resources:

• www.blackberry.com/go/devdocs: Find development guides, release notes, API references and sampleapplication overviews for the various BlackBerry application development approaches.

• www.blackberry.com/go/apiref: View the latest version of the API reference for the BlackBerry® Java® SDK.• www.blackberry.com/developers: Visit the BlackBerry® Developer Zone for resources on developing BlackBerry

device applications.• www.blackberry.com/go/developerkb: View knowledge base articles on the BlackBerry Development

Knowledge Base.• www.blackberry.com/developers/downloads: Find the latest development tools and downloads for developing

BlackBerry device applications.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

40

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

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

41

Glossary 7AES

Advanced Encryption Standard

BlackBerry transport layer encryptionBlackBerry transport layer encryption (formerly known as standard BlackBerry encryption) uses a symmetric keyencryption algorithm to help protect data that is in transit between a BlackBerry device and the BlackBerry®Enterprise Server when the data is outside an organization's firewall.

BlackBerry Enterprise Server environmentA BlackBerry® Enterprise Server environment consists of one or more BlackBerry Domain instances, a messagingserver, and any third-party software and hardware that the BlackBerry Enterprise Server components interactwith.

certificateA certificate is a digital document that binds the identity and public key of a certificate subject. Each certificatehas a corresponding private key that is stored separately. A certificate authority signs the certificate to indicatethat it is authentic and can be trusted.

CLDCConnected Limited Device Configuration

code-signing keysCode-signing keys are the keys that are stored on media cards that sign files so that a user can install and run thefiles on a BlackBerry device.

content protectionContent protection helps protect user data on a locked BlackBerry device by encrypting the user data using thecontent protection key and ECC private key.

HTTPSHypertext Transfer Protocol over Secure Sockets Layer

IT policyAn IT policy consists of various IT policy rules that control the security features and behavior of BlackBerrysmartphones, BlackBerry® PlayBook™ tablets, the BlackBerry® Desktop Software, and the BlackBerry® WebDesktop Manager.

IT policy ruleAn IT policy rule permits you to customize and control the actions that BlackBerry smartphones, BlackBerry®PlayBook™ tablets, the BlackBerry® Desktop Software, and the BlackBerry® Web Desktop Manager can perform.

JDK

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

42

Java® Development Kit

JVMJava® Virtual Machine

Java MEJava® Platform, Micro Edition

MIDPMobile Information Device Profile

S/MIMESecure Multipurpose Internet Mail Extensions

TCP/IPTransmission Control Protocol/Internet Protocol (TCP/IP) is a set of communication protocols that is used totransmit data over networks, such as the Internet.

WAPWireless Application Protocol

WTLSWireless Transport Layer Security

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

43

Document revision history 8

Date Description

13 July 2011 Initial release

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

44

Legal notice 9©2011 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, and relatedtrademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in theU.S. and countries around the world.

Bluetooth is a trademark of Bluetooth SIG. Eclipse is a trademark of Eclipse Foundation, Inc. Facebook is a trademarkof Facebook, Inc. GSM is a trademark of the GSM MOU Association. Intel and Pentium are trademarks of IntelCorporation. Java, JavaScript, and NetBeans are trademarks of Oracle America, Inc. OpenGL is a trademark of SiliconGraphics, Inc. OpenVG is a trademark of Khronos Group Inc. SQLite is a trademark of Hipp, Wyrick & Company, Inc.SVG Tiny is a trademark of W3C. Twitter is a trademark of Twitter, Inc. Wi-Fi is a trademark of the Wi-Fi Alliance. Allother trademarks are the property of their respective owners.

This documentation including all documentation incorporated by reference herein such as documentation providedor made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" andwithout condition, endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limitedand its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or otherinaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidentialinformation and/or trade secrets, this documentation may describe some aspects of RIM technology in generalizedterms. 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 thisdocumentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, productsor 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 ThirdParty 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. Theinclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement byRIM 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 ORWARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLEQUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM ORA COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCEOR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICESREFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE ORPROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES ANDCONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THEDOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, AREHEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEMTHAT IS THE SUBJECT OF THE CLAIM.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

45

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BELIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICESREFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT,CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGESFOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSSOF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TOTRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITHRIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTIONTHEREOF 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 ORUNFORESEEN, 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 OTHEROBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANYLIABILITY FOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THECAUSE 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 BREACHOR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINEDHEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS(INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICEPROVIDERS) 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 ANYLIABILITY 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 ensurethat your airtime service provider has agreed to support all of their features. Some airtime service providers mightnot offer Internet browsing functionality with a subscription to the BlackBerry® Internet Service. Check with yourservice provider for availability, roaming arrangements, service plans and features. Installation or use of Third PartyProducts and Services with RIM's products and services may require one or more patent, trademark, copyright, orother licenses in order to avoid infringement or violation of third party rights. You are solely responsible fordetermining 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 Servicesuntil all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM'sproducts and services are provided as a convenience to you and are provided "AS IS" with no express or impliedconditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liabilitywhatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject toyou agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, exceptto the extent expressly covered by a license or other agreement with RIM.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

46

Certain features outlined in this documentation require a minimum version of BlackBerry® Enterprise Server,BlackBerry® Desktop Software, and/or BlackBerry® Device Software.

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicablethereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS ORWARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THISDOCUMENTATION.

Research In Motion Limited295 Phillip StreetWaterloo, ON N2L 3W8Canada

Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom

Published in Canada

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

47