BlackBerry Java SDK

mongooseriverSoftware and s/w Development

Jun 7, 2012 (5 years and 5 months ago)

1,071 views

BlackBerry Java SDK
Version: 7.0
Getting Started Guide
Published: 2011-09-22
SWD-1641291-0922050442-001
Contents
1
Introduction......................................................................................................................................................
3
Getting help with Java development................................................................................................................
3
2
Creating a successful app..................................................................................................................................
4
Designing your app...........................................................................................................................................
5
3
Java development tools....................................................................................................................................
7
About the BlackBerry Java plug-in for Eclipse...................................................................................................
7
Simulators.........................................................................................................................................................
8
Code signing keys..............................................................................................................................................
8
4
Creating your first app......................................................................................................................................
9
Create the Hello BlackBerry app.......................................................................................................................
9
Running your app..............................................................................................................................................
10
Run your app in a simulator......................................................................................................................
10
Run your app on a smartphone.................................................................................................................
11
More tutorials...................................................................................................................................................
11
5
Introducing the Java SDK..................................................................................................................................
12
Application lifecycle APIs..................................................................................................................................
12
UI API................................................................................................................................................................
14
Application integration APIs.............................................................................................................................
16
PIM APIs............................................................................................................................................................
19
Messaging APIs.................................................................................................................................................
19
Network Connection APIs.................................................................................................................................
21
CLDC Platform and Utilities APIs.......................................................................................................................
23
Device characteristics and BlackBerry infrastructure.......................................................................................
24
Data storage APIs..............................................................................................................................................
26
Multimedia API.................................................................................................................................................
27
Location-Based Services API.............................................................................................................................
28
Security APIs.....................................................................................................................................................
30
Support for Java ME APIs..................................................................................................................................
32
6
Provide feedback..............................................................................................................................................
33
7
Glossary............................................................................................................................................................
34
8
Document revision history................................................................................................................................
36
9
Legal notice.......................................................................................................................................................
37
Introduction
1
Welcome to BlackBerry® Java® development. This guide will help you get started creating mobile apps for the
BlackBerry smartphone. In this guide you will find:
• Tips for creating a successful app
• An introduction to the tools you need to develop BlackBerry Java apps
• A tutorial showing you how to create a simple app
• An introduction to the APIs in the BlackBerry® Java® SDK
This guide is designed to be a gateway to BlackBerry Java development resources, and so provides links to further
information in the BlackBerry Java SDK dev guides and the BlackBerry Developer Zone.
Getting help with Java development
When 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)
• 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:
• Java development guides
• Java sample apps
• Java API Reference
• Developer Resources
• BlackBerry.com Developer Zone Java getting started page
• BlackBerry developer blog
• Knowledge base for Java development
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
3
Creating a successful app
2
Research In Motion® provides the following solutions to help you achieve success with your apps. All of these services
are provided free of charge.
The Advertising Service, Payment Service, and Analytics Service are all separate SDKs so that they are not dependent
on 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 byRIM for you to sell your apps. There is no cost to you to register
with App World or to use it to sell your apps. App World comes pre-loaded on new BlackBerry smartphones.
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 SDK is designed to
allow you to integrate ads into your apps without writing a lot of code. Using the web portal, you can modify ad
content after your app is released (such as changing your ad networks), and track statistics about your ads.
For more information, see:
• Advertising Service
• Advertising Service developer guides and API reference
Collect money in your app
The Payment Service is an SDK that you can use to collect money in your apps. Your customers can use any of the
payment 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 the 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 your users such as their BlackBerry smartphone model, version, country of origin, and
language; the number of unique users, the total number of sessions, and the average length of a session; and data
such as screen views, button clicks, and application errors. The Analytics Service collects the data, compiles it, and
produces reports and metrics on a web portal.
For more information, see:
• Analytics Service
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
4
• Analytics Service developer guides and API reference
Designing your app
This section provides some of the basic steps for designing 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 will
be sold on BlackBerry 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 the
BlackBerry® 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 BlackBerry
Device Software 4.7.
For more information about designing apps for multiple versions, see:
• Migrate your app to BlackBerry 7
• Develop applications for different BlackBerry device 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)
In the BlackBerry Java Plug-in for Eclipse, you can package your BlackBerry application project (and its dependent
projects) for multiple versions of BlackBerry Device Software. When you distribute your app, the plug-in creates one
master .alx file in the Standard folder of your BlackBerry application project. When you distribute your app over the
Internet, the plug-in creates the .jad and .cod files for each version of the BlackBerry Device Software in the Web
folder of your BlackBerry application project.
For more information about packaging application projects for multiple versions, see BlackBerry Java Plug-in for
Eclipse development guides.
Decide which BlackBerry features to integrate into your app
Successful smartphone apps (especially in the consumer market) take advantage of the technology of the
smartphone. For example, they integrate with social networking, calendars, cameras, GPS, or push capability. Some
BlackBerry smartphones contain magnetometers (a three-axis compass that detects direction), accelerometers (that
detect movement of the smartphone in 3-D space), NFC sensors, and more.
For information about BlackBerry features and how to make the most of them in your app, see:
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
5
• 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 Navigation
Development Guide.
For more information about NFC, see the BlackBerry Java SDK Networking and Connectivity development guide.
For information about new features of BlackBerry Java SDK 7, see:
• Migrate your app to BlackBerry 7
• BlackBerry Java SDK 7 New in this Release
Review BlackBerry Design Guidelines
Research In Motion® has conducted extensive research to develop best practices and design tips for you to use when
designing a user interface. For more information, see BlackBerry Smartphone 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. They are installed as part of the BlackBerry Java Plug-in
for Eclipse.
All of the sample apps are documented with code comments. Some of them also have user guides. You can find the
user guides at Java sample apps.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
6
Java development tools
3
The BlackBerry® Java® Plug-in for Eclipse® includes the BlackBerry Java SDK. The plug-in also includes functionality
to simplify your development efforts, such as tools to compile your code into the files you need for BlackBerry
deployment.
This section describes the development tools you can use for BlackBerry® smartphone application development.
About the BlackBerry Java plug-in for Eclipse
Eclipse® is a free, open source development tool. To extend Eclipse for BlackBerry development, RIM provides the
BlackBerry® Java® Plug-in for Eclipse, also free of charge. The plug-in simplifies Java application development for
BlackBerry 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 apps. 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 on
a 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 view
information about application .cod files.
• BlackBerry Signature Tool: You can use this tool to send code signature requests to the BlackBerry® Signing
Authority Tool.
• Preverify Tool: You can use this tool to partially verify your classes before you load your application onto a
smartphone.
• 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 into
Eclipse with the BlackBerry Java Plug-in for Eclipse. After version 1.1, the BlackBerry Java Plug-in for Eclipse no longer
supports project files (.jdp) and workspace files (.jdw) and is not backward compatible with the BlackBerry JDE.
Installing the BlackBerry Java Plug-in and the Eclipse IDE
To install the Eclipse IDE or the BlackBerry Java Plug-in, you must have an account on the BlackBerry Developer Zone.
Registration is free.
You can download the Eclipse IDE and plug-in together. If you already have Eclipse installed, you can choose to install
the Eclipse IDE with the BlackBerry Java Plug-in in a different directory, or you can overwrite your existing installation.
Here are the download sites for Eclipse with the plug-in:
• BlackBerry Java Plug-in for Eclipse v1.3 (Windows)
• BlackBerry Java Plug-in for Eclipse v1.3 (Mac)
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
7
If you already have Eclipse Classic 3.6.x installed, you can install the plug-in and SDK without reinstalling Eclipse. You
can do this in Eclipse, either through Help > Install New Software (you must specify a BlackBerry update site to do
this) or Window > Preferences (expand the Java item and select Installed JREs).
Once you have the plug-in installed, you can update the version of the JavaSDK or remove the Java SDK.
You can find complete installation instructions here: BlackBerry Java Plug-in for Eclipse Development Guides (for
Windows and Mac).
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
Simulators
When you install the BlackBerry® Java® Plug-in for Eclipse®, a simulator is included in the download. However, it is
good practice to test your app on simulators for several smartphone models. You can download other BlackBerry
simulators free of charge.
For more information about simulators and how to download them, see:
• BlackBerry Smartphone Simulators
• BlackBerry Smartphone Simulator development guides
Code signing keys
Some BlackBerry® APIs require code signing keys. When you use these APIs, you can test your app in a simulator but
can't deploy it until you use your key to sign the application. In the API reference, elements that require code signing
keys 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. Your
keys will be sent to you by email, along with instructions for how to use them.
For more information about using code signing keys, see the BlackBerry Java SDK Security development guide.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
8
Creating your first app
4
The BlackBerry® Java® Plug-in for Eclipse® provides templates you can use to create a basic app. You can customize
the code in the template to suit your needs, or you can create an app from scratch with an empty template.
To get you started, we'll create a version of the "Hello World" app with the Hello BlackBerry template. This version
of "Hello World" is a basic UI application that provides some simple UI components. The app includes an editable
text field that allows the smartphone user to type text in a field; in this example, they can type their name. The app
also includes a button field. When the smartphone user types their name and clicks the Say Hello to button, the app
displays a dialog box with the text Hello <username> as shown in the following screenshot.
Create the Hello BlackBerry app
Before you begin: In the BlackBerry® Java® Plug-in for Eclipse®, make sure you turn on the BlackBerry Application
Development perspective. Click Window > Open Perspective > Other and then choose BlackBerry Application
Development.
1.From the BlackBerry menu, click New > BlackBerry Project.
2.In the Project name field, type HelloBlackBerry.
3.In the New BlackBerry Project dialog, select Create new project in workspace.
4.Under JRE, select Use a project specific JRE and then choose BlackBerry JRE 7.0.0 from the dropdown list.
5.Click Next.
6.Click Next.
7.Select the Hello BlackBerry template.
8.Click Finish.
In the list of projects in the Package Explorer pane, the HelloBlackBerry project appears. You can expand the project
to see that the src/mypackage folder contains two Java® source files:
• HelloBlackBerry.java: This file contains the source code for the main section of the app.
• HelloBlackBerryScreen.java: This file contains the source code for generating the screen.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
9
Running your app
You can run and test your app on a BlackBerry® Smartphone Simulator or a BlackBerry smartphone.
The BlackBerry® Java® Plug-in for Eclipse® includes simulators for various BlackBerry smartphone models. The
simulators run the same Java® code as the smartphones, so a simulator provides an accurate environment for testing
how your app will function on a BlackBerry device.
Run your app in a simulator
In the following steps, we'll use the Hello BlackBerry app that we created earlier to demonstrate how to run an
application.
1.In the Package Explorer pane, select the project you want to run. For this example, select the HelloBlackBerry
project.
2.To run the app in a simulator, 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, then from the BlackBerry toolbar, click
the Run on BlackBerry Simulator button.
The BlackBerry® Java® Plug-in for Eclipse® builds and packages the project, and then launches the BlackBerry
Smartphone Simulator.
3.On the Home screen of the simulator, click the application icon. In this example, click the Hello BlackBerry icon.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
10
The HelloBlackBerry app opens and displays a screen with an editable text field and a button.
4.To test the Hello BlackBerry app, type your name in the Enter Name field, and then click the Say Hello to button.
A dialog box displays with the text Hello <your name> and an OK button. Click OK.
5.To close the app on the simulator, press the Menu key, and then select Close.
6.To close the simulator, click File > Exit.
Run your app on a smartphone
Before you begin: If your app uses protected Research In Motion® APIs, you must first get code signing keys from
RIM. For more information about code signing and registering with RIM to use protected APIs, see
www.blackberry.com/SignedKeys
1.Connect the BlackBerry® smartphone to your computer with a USB cable.
2.In the Eclipse® Package Explorer pane, right-click the project that you want to load on the device.
3.Click BlackBerry > Load Project(s) on Device.
The BlackBerry® Java® Plug-in for Eclipse® builds and packages the project. If the smartphone 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 smartphone, click the application icon to run the app.
More tutorials
Here are some more advanced tutorials:
• Tutorial: Creating a custom button
• Tutorials in the Java developer support forums
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
11
Introducing the Java SDK
5
The BlackBerry smartphone is built from the ground up as a Java-based device, with all built-in apps and APIs written
in Java. The BlackBerry® Java® SDK includes Java® ME APIs and BlackBerry-specific APIs. The BlackBerry APIs provide
access to advanced UI functionality, deep integration with existing applications, the ability to create databases with
SQLite® 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 SDK is divided into twelve categories. Each category consists of APIs that provide a separate type
of functionality, such as UI creation, networking, data storage, and security. Many of the categories include both
Java ME APIs and BlackBerry-specific APIs.
All twelve categories that make up the BlackBerry Java SDK are described in the following sections.
Application lifecycle APIs
The lifecycle of an application refers to the possible states and transitions that an app can move through from the
time it starts until it terminates. The lifecycle of a BlackBerry® app is straightforward: it starts, runs, and terminates.
During the running state, most apps receive and process events and update their UI accordingly.
All apps have an application class derived from either Application or UiApplication. If you want to create an app with
a UI, then your app should extend UiApplication. Otherwise, your app should extend Application.
Starting
A BlackBerry app 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 app starts the app.
• The system starts the app at a scheduled time.
Running
Regardless of how an app is started, the Application Manager is responsible for starting the process that the app
runs within. The ApplicationManager class enables apps to interact with the Application Manager to perform tasks,
including:
• Run an app immediately or at a scheduled time.
• Interact with processes, including retrieving the IDs for foreground apps.
• Post global events to the system.
The Application Manager starts an app by getting a new process and spawning a thread within that process to call
one of the entry points of the app. For many apps, the main() method of its application class is the single entry point
that is called. However, you can configure more than one entry point for an app. Multple entry points allow users to
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
12
start the app in different ways. For example, if your app allows users to create a new document, you might want to
provide users with two icons that they can click to start the app. Users could click one icon to open the app in its
home screen and the other icon to open the app in the screen required to create a new document.
Application descriptors are sets of data about an app. A single app can have more than one associated application
descriptor. An app that has multiple entry points has an application descriptor corresponding to each of those entry
points. You can use the ApplicationDescriptor class to work with application descriptors.
The BlackBerry operating environment is multi-threaded. It enables you to run multiple apps simultaneously. It
supports broadcasting events to multiple apps and running background threads.
The event thread is the only thread that can process events and update the UI of the app, so you must not use it to
run instructions that could fail or take a long time to complete. If, for example, you need to make a network
connection, you must spawn and use another thread.
You may encounter situations where you want to update the UI from a non-event thread. There are two ways to do
that:
• You can use background threads to access the UI by acquiring the event lock for a short time. This option is
useful if you need to perform a quick or urgent UI update. In this case, you must quickly complete the UI update
you require and release the lock. Otherwise, your application will become unresponsive and might eventually
be terminated by the system. You acquire the event lock by calling Application.getEventLock() on the background
thread, and then synchronize this object to serialize access to the UI.
• You can add a runnable object to the event queue. This option is preferable if it is acceptable to experience a
delay before your task runs. You inject an event in the form of an object that implements Runnable. The event
is handled by the event thread as it is received from the message queue. The event thread processes the event
by calling its run() method. To inject runnable events in the message queue of your app, use the invokeAndWait()
method or the invokeLater() method.
In either case, you should not run tasks that might take a long time to complete or might block. If you use library
calls within your task, be sure you understand them well and only use them if they will finish quickly and not block.
Terminating
One way to terminate an app is to invoke System.exit(), which causes the BlackBerry JVM to terminate all of the
processes of the caller and, as a result, all associated threads. Alternatively, you can terminate an app by 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 app.
Because you will typically start the event dispatcher thread by calling Application.enterEventDispatcher(), which
doesn't terminate, your app should provide a way to terminate. Apps that interact with the user could provide a
handler for a Close menu item, and apps that do not interact with the user might terminate upon handling some
system event that represents their reason for existence.
More information about the application lifecycle
• UI lifecycle
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
13
UI API
The UI API helps you create user interfaces for BlackBerry® screens.
Apps with a UI implement net.rim.device.api.ui.UiApplication, which is a subclass of
net.rim.device.api.system.Application. A UIApplication object maintains a stack of Screen objects. As it pushes
screens onto the stack, it draws them on top of any other screens already on the stack. When the application pops
a screen off the stack, it redraws the underlying screens as necessary. Only the screen on the top of the stack receives
input events.
The three main UI objects are Field, Manager, and Screen.
Fields
A Field represents a rectangular region contained by a manager. Each control, such as a button, corresponds to an
instance of a field. You can't instantiate Field directly, but you can use prebuilt fields and create custom fields. Each
field draws the control and handles user input. Following are some of the most commonly used prebuilt fields:
• 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
You can create custom fields by extending the Field class.
Managers
A Manager, also called a layout manager, handles the layout and scrolling of fields. A Manager object contains fields.
There are several Manager subclasses that handle specific types of field layout.
Several useful managers are defined in the net.rim.device.api.ui.container package. The following managers are the
most commonly used:
• VerticalFieldManager arranges fields in a single vertical column
• HorizontalFieldManager arranges fields in a single horizontal row
• FlowFieldManager arranges fields first horizontally, then vertically
You declare a layout manager at the top level of your screen and then add fields to it. Because layout managers are
subclasses of Field, they can be embedded in other layout managers. You can also define your own layout manager.
Screens
A Screen is the top-level container for the UI elements that represent what you want to display. Screens can contain
fields (such as text fields), layout managers, radio buttons, and dropdown lists.
The UI API has two main types of Screen object:
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
14
• FullScreen, which is subclassed by MainScreen and PhoneScreen
• PopupScreen, which is subclassed by Dialog, Status, LocationPicker, and AbstractLocationPicker
You can display information that is supplementary to your application in a pop-up screen without interrupting the
flow 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 invoking
pushGlobalScreen(Screen, int, int).
Screen objects are pushed on to the display stack by the pushScreen() and pushModalScreen() methods of the
UiApplication class. Because pushModalScreen() blocks until the screen is popped off the display stack (where
pushScreen() returns immediately), the order of operations is crucial when you use modal screens. Do not invoke
pushModalScreen() before starting the event dispatcher thread; doing so throws a RuntimeException. Other
methods, such as Dialog.inform() and Dialog.alert(), also use pushModalScreen().
Menus
BlackBerry smartphones organize commands on context-sensitive menus that can be accessed by pressing the Menu
key. Menu items are instances of MenuItem. You can customize the menu that is opened for your app. You can:
• Add or remove menu items depending on the screen or application state when the menu opens
• Specify the order of menu items
• Specify the menu item that is selected by default
Listeners
The UI API contains a generic event listener model that lets you implement listeners for many types of events, such
as when a field is changed, or when the user presses a key, clicks the trackpad or trackball, or touches the touch
screen. You can set a listener for a Field object by invoking setChangeListener() of the Field class.
Model-View-Controller design pattern
Some standard components in the UI API, including activity and progress indicators in the
net.rim.device.api.ui.component.progressindicator package and lists and tables in the
net.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 online
resources where you can learn about MVC.
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.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
15
• You can create 3D images using the OpenGL ES API.
More information about the user interface
• Tutorial: Creating a custom button
• BlackBerry Java SDK UI and Navigation development guide
• BlackBerry Smartphone UI Guidelines
• BlackBerry Java SDK UI Component development guide
• BlackBerry Java SDK Graphics and Animation development guide
• BlackBerry Java SDK Augmented Reality development guide
Application integration APIs
The Application integration APIs contain packages you can use to integrate your apps with core applications such as
the 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, call
invokeApplication and pass in the application type and any relevant arguments. You can use the Invoke API to invoke
the following core applications:
• contacts
• calculator
• calendar
• camera
• BlackBerry Maps
• memos
• messages
• phone
• search
• tasks
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 the
ApplicationArguments class. For example, to invoke the Phone application, call invokeApplication and pass in the
Phone application type and a PhoneArguments argument. To invoke an application with no arguments, pass in null
instead of an ApplicationArguments object.
Content Handler API
You can use the Content Handler API (CHAPI) to invoke both core applications and third-party apps. JSR 211 defines
CHAPI as a Java® ME-optional API. For more information about CHAPI, see the javax.microedition.content package
overview.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
16
To use CHAPI to invoke applications, provide a URL, a content type, or a content ID with one of the constructors in
the javax.microedition.content.Invocation class. When you use CHAPI with the RIM provided content IDs for invoking
RIM® content handlers, CHAPI can be a good way to set invocation parameters for core applications, including the
Media application. You can also use CHAPI to invoke third-party apps that register as content handlers.
BlackBerry Browser
You can invoke the BlackBerry Browser and open a web page with the methods in the Browser class and the
BrowserSession class.
For more information about invoking a browser, including how to invoke a browser that is not specified as the default
browser, see the Knowledge Base article Invoke the browser.
You can also embed web content in your app 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 cannot
pass application arguments to a core application with this technique. You can use ApplicationManager to invoke
the following core applications:
Application
Module name
clock
net_rim_bb_clock
sounds
net_rim_bb_profiles_app
BlackBerry
Messenger
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 unintended
side-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 item
called View Sales Order to the Contacts application. When the user clicks View Sales Order, your application opens
and displays a list of sales orders for that contact.
The ApplicationMenuItemRepository class provides the constants that specify the core application that your menu
item appears in. For example, the MENUITEM_MESSAGE_LIST constant specifies that the menu item appears in the
Messages application. The MENUITEM_SYSTEM constant specifies that your menu item appears in most core
applications.
The applications that use the ActiveAutoTextEditField or the ActiveRichTextField field (for example, the Calendar and
Messages applications) can recognize string patterns and provide specific items for those string patterns in the menu
on the smartphone. For example, if a message contains a phone number, the number is highlighted. If the smartphone
user selects the number and presses the Menu key, the special menu item Call Number displays.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
17
You can define your own string patterns and associate the patterns with custom menu items. The custom menu items
display when a user selects a matching string in an ActiveAutoTextEditField or ActiveRichTextField field
and opens the menu. The custom menu items can perform any action, such as starting your app.
You can use the PatternRepository class to register a Perl-style regular expression or a specific string with the pattern
repository on the smartphone. You can use the ApplicationMenuItem class to define a menu item that is associated
with the string pattern.
For more information about PatternRepository and active text fields, see Active Text Fields sample application.
You can register the content handlers that invoke your app by using the Registry class, which is provided in the
Content Handler API. When you register a content handler, you can provide an array to specify the actions that invoke
the handler. ContentHandler.ACTION_OPEN content handlers for the MIME types that are not supported by the
smartphone are used in the BlackBerry Browser, file explorer, and in the Open Attachment menu item in the Messages
application. ContentHandler.ACTION_SEND content handlers for the image or video MIME types are used in the
file explorer (including in the Media application) and in the Send As menu in the Camera application.
Embedding content in BlackBerry applications
You can embed content in apps in several ways, including the following:
• Add apps to the Messages application using the messagelist package
• Link contacts in your appl with contacts in the Contacts application using the contactlinking package
• Add content to phone screens using the phonequi pacakge
• Add options for your app using the options package
• Register your app as a notification source using the notification package
Embedding UI components in your app
You can include in your apps 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
• 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
Unified search
The Unified Search Service is a search engine that is included with BlackBerry Device Software 6 and later. You can
use the Unified Search API (net.rim.device.api.unifiedsearch) to include your application data in the Unified Search
Service's content repository, and to search the content index from your application.
More information about application integration
• BlackBerry Super Apps
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
18
• BlackBerry Java SDK Super App development guide
• BlackBerry Java SDK Integration development guide
• BlackBerry Java SDK UI and Navigation development guide
PIM APIs
The PIM APIs include packages that allow you to access address books, calendars, tasks, and memopads from your
application. The BlackBerry® smartphone fully supports the J2ME® PIM implementation established in JSR 75, and
provides a number of custom extensions.
The javax.microedition.pim package provides interfaces that allow you to access PIM data on a smartphone. PIM
data is organized into PIM lists, items, and fields. PIM lists are databases that contain all PIM items. PIM lists maintain
categories, which are logical groupings for the PIM items contained in the list. Each PIMList object can support zero
or more categories. Categories are represented by unique String 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 particular
PIM list and is associated with that list for the life of the item. A PIM item can have its data imported and exported
using standard byte-based formats. Each implementing class defines what formats can be imported and exported
for that item.
You can launch PIM applications with the BlackBerry Invoke API.
RIM extensions
RIM® extensions to J2ME PIM are in the net.rim.blackberry.api.pdap package. These extensions 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)
More information about PIM
• BlackBerry Java SDK Integration development guide
• PIM API category overview
Messaging APIs
The Messaging APIs allow you to use messaging functionality in your apps, including emails, application messages,
SMS, MMS, and BlackBerry® Messenger.
Email messages
The packages for email messages are net.rim.blackberry.api.mail and net.rim.blackberry.api.mail.event.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
19
To create and send email messages, set the default Session, retrieve a Store instance, create the email message, and
store the email in a retrieved sent folder. Finally, set up and send the email message.
To send an email message with an attachment, create the Multipart object, create and add the attachment file to
this object, and structure and send the email message. To automatically download attachments in email messages
in the background when messages arrive in the message list, use the DownloadProgressListener interface and the
AttachmentDownloadManager class.
PIN messages
Each BlackBerry smartphone has a unique PIN and supports PIN-to-PIN messaging sent with the Messages application.
To create and send PIN messages, set the default Session, retrieve a Store instance, set the destination PIN address,
create the PIN message, and store the message in a retrieved sent folder. Finally, set up and send the PIN message.
Application messages
An ApplicationMessage is a custom message that appears in the Messages application. The message invokes your
app either when the user opens it or when the user chooses a menu item that you provide for the message. Use the
messagelist package to create application messages.
SMS and MMS messages
You can create apps that send and receive SMS messages or MMS messages. SMS support is provided through JSR
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 send
SMS 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 using
an earlier version of the SDK, use the MessageConnection interface.
MMS messages consist of an MMS header and body. The MMS header consists of address, priority, subject, and
delivery information. The MMS body contains the multimedia attachment portion.
To receive MMS messages when using the BlackBerry Java SDK 4.6.0 or later, use the MessageListener interface. If
you are using an earlier version of the BlackBerry JDE, use the MessageConnection interface.
Sending MMS messages is similar to sending SMS messages, except that you must pass in the MULTIPART_MESSAGE
constant when creating the MessageConnection object. To listen for incoming MMS messages that appear in the
message list, set the selected Connector.open() application ID to 0.
In addition to providing notification to applications when messages are received (using the MessageListener
interface), 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 class
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
20
that implements the OutboundMessageListener interface when invoking
MessageConnection.setMessageListener(). Notification using this interface occurs only after the message is sent
successfully. If the send operation fails, the application is not notified.
BlackBerry Messenger
BBM is an instant messaging program that lets BlackBerry smartphone users communicate with each other without
signing into or out of the application. As long as smartphones are connected to a wireless network, BBM can keep
users connected to their BBM contacts and groups.
The BlackBerry Messenger SDK is a separate download from the BlackBerry Java SDK. The BBM SDK, used in
conjunction 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 game
application, a BlackBerry smartphone user could invite a BBM contact to play a game of chess, and the moves could
be 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 development guides.
More information about messaging
• BlackBerry Java SDK Integration development guide
• Messaging category overview
Network Connection APIs
The Network Connection APIs contain packages to manage input and output data streams. The APIs provide a wide
range of functionality. You can use them to connect and work with everything from a microSD form factor smart card
to 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 to
communicate over wireless connections. BlackBerry smartphones work with different network transport methods
over 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 are
supported by a smartphone. You can then use the TransportInfo.isTransportAvailable() method to determine
whether the smartphone is currently capable of using the supplied transport type. Finally, you can test the coverage
of the transport type by using TransportInfo.hasSufficientCoverage(). After that sequence of probing calls, you know
what transports are available and whether the smartphone is in coverage for your transport of choice.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
21
The Network API does not make connection creation thread-safe. Your application will lock if you call
ConnectionFactory.getConnection() on the event thread. When calling this method to create a connection, create a
non-event thread.
The simplest way to use the ConnectionFactory class to create a connection is to call the
ConnectionFactory.getConnection() method, specifying only the URL to connect to. The method will return a
ConnectionDescriptor object from which you can call ConnectionDescriptor.getConnection() to retrieve a Connection
object that you can cast to an appropriate subobject.
The BlackBerry solution also enables server-side applications to proactively push data to BlackBerry smartphones in
a 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 output
operations. 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 Connector
class. You call Connector.open() to create any type of supported connection. The first parameter to
Connector.open() is a URI (as described in RFC 2396) that specifies the type of connection to make, the endpoint
to connect to, and optional connection configuration details. When the connection is established, a connection
interface that corresponds to the type of connection that was created is returned from the call to
Connector.open(). You cast the returned connection interface to the appropriate connection subtype according
to the URI you specified.
NFC
With the NFC API you can read and write data on smart tags, emulate a smart tag, and access a Secure Element
embedded on a BlackBerry smartphone or a SIM card. The NFC API supports most major tag types. NFC is provided
in the net.rim.device.api.io.nfc package.
You can check whether a smartphone supports NFC with the DeviceCapability classes in the
net.rim.device.api.system.capability package.
To read and write to smart tags, you can register your app to receive notifications when a BlackBerry smartphone
detects a tag. You can register listeners with the ReaderWriterManager class in the net.rim.device.api.io.readerwriter
package. You can set up a smartphone to emulate a smart tag with the net.rim.device.api.io.nfc.emulation package.
To connect smart accessories to your device, you can use the
net.rim.device.blackberry.api.accessory.AccessoryManager class. You can use the net.rim.device.api.io.nfc.se
package to access a Secure Element.
Other types of connection
• LDAP: net.rim.device.api.ldap
• Push service: Client-side (net.rim.device.api.push) and server-side (Push Service development guides)
• Smart cards and smart card readers: net.rim.device.api.smartcard and BlackBerry Java SDK Smart Card
development guide
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
22
• Javacards: javax.microedition.jcrmi
More information about network connections
• Network Connections category overview
• BlackBerry Java SDK Networking and Connectivity development guide
• Network Transports tutorial
CLDC Platform and Utilities APIs
The 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 provide
the core set of APIs for developing applications on resource-constrained wireless devices, such as BlackBerry®
smartphones.
• 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 for
Java® ME devices, such as a BlackBerry smartphone, to act as a web service client using standard programming
interfaces.
• 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.
For example, you can use RIM provided collection classes, such as BigVector or UnsortedReadableList, instead of the
standard Vector class.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
23
In some cases, RIM provides classes that exist inJava SE but are not provided (or only partially provided) in standard
Java ME. For example:
• net.rim.device.api.xml.parsers supplements javax.xml.parsers by adding DocumentBuilder and
DocumentBuilderFactory, 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 available
in 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 suitable
for use in wireless applications.
• net.rim.device.api.xml.jaxp package provides support for XML processing and supplements org.xml.sax by
adding extensions to the standard helper classes
The RIM-provided packages in the CLDC Platform and Utilities category are:
• Web-service and XML-related packages: net.rim.device.api.xml, net.rim.device.api.xml.jaxp, and
net.rim.device.api.xml.parsers
• Collections-related packages: net.rim.device.api.collection, net.rim.device.api.collection.util, and
net.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 infrastructure
The packages in these APIs include classes that let you query for details about the hardware and other characteristics
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 the
smartphone supports audio mixing and what time zone is currently set.
You can use the DeviceCapability class to query whether covered capabilites are supported, allowed, or available.
Using the Service Book API (net.rim.device.api.servicebook), your app can interact with the service book on the
smartphone. For example, you can use a service record to keep track of multiple email connections or search for
individual emails within an email hierarchy based on the email item's content ID.
The following classes, mostly in the net.rim.device.api.system package, provide methods to obtain additional
information about a smartphone:
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
24
Class
Methods provide information such as...
AccelerometerSensor
Whether the smartphone has an accelerometer
Audio
Whether the smartphone supports audio, codecs, a headset; whether the headset
is connected; volume
Backlight
Whether the backlight is on and whether brightness is configurable; brightness,
default brightness, and backlight timeout
BluetoothSerialPort
Whether Bluetooth is supported; information about Bluetooth
Branding
Vendor ID, branding data version, whether branding data is signed
CDMAInfo
Electronic serial number (ESN) and mobile equipment identifier (MEID) of the
smartphone
DeviceInfo
Platform version, software version, manufacturer name, PIN, device ID, device
name, whether this is a simulator, battery level, battery status, battery
temperatures, battery voltage, whether the battery is removable, whether there
is a camera, flash memory size
Display
Properties such as subpixels and the requirement for backlight; horizontal and
vertical resolution; drawable height and width; number of display colors
GPRSInfo
International Mobile Equipment Identity (IMEI)
GPSInfo
Whether the smartphone supports GPS; default GPS mode
LED
Whether LED is supported, whether LED is multicolor
Memory
RAM statistics, flash memory size, amount of free flash memory
OwnerInfo
Owner information, owner name
Phone
Phone number; whether voicemail is activated
RadioInfo
Supported wireless access families
Sensor
Whether the smartphone has a flip and whether it is open; whether it has a holster
sensor and whether it is in its holster; whether it has a sliding keyboard and the
keyboard state
SIMCardInfo
International Mobile Subscriber Identity (IMSI) number
USBPort
Whether there is a USB port; USB connection state
BlackBerry infrastructure
Research In Motion® provides two basic types of infrastructure: BlackBerry® Enterprise Server and BlackBerry®
Internet Service.
The BlackBerry Enterprise Server is a wireless solution with advanced security features for organizations with IT
departments. The BlackBerry Enterprise Server exists behind the corporate firewall and integrates with an
organization's existing infrastructure. It is designed to be a secure, centralized link between an organization's wireless
network, communications software, applications, and BlackBerry smartphones. Administrators can apply IT policy
rules and application control policies to control the smartphones that are used in the organization. For Java®
developers in a BlackBerry Enterprise Server environment, there are many relevant APIs, including the IT Policy API,
net.rim.device.api.itpolicy, and the Application Control API, net.rim.device.api.applicationcontrol.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
25
The BlackBerry Internet Service is an email and Internet service that is designed to provide users with automatic
delivery of email messages, mobile access to email message attachments, and convenient access to Internet content.
The BlackBerry Internet Service uses the security of the wireless network it connects to. Email messages that are
sent between the BlackBerry Internet Service and a BlackBerry smartphone are not encrypted. When email messages
are sent over the wireless network, they are subject to the existing or available network security models. However,
email messages that are sent between the BlackBerry Internet Service and a messaging server can be encrypted using
Secure Sockets Layer (SSL) encryption. SSL encryption can also be used by the browser and other applications on a
BlackBerry smartphone to help protect data when a user connects to the Internet (for example, while shopping and
banking online).
Push service
The push service provides an efficient and reliable way to send information to BlackBerry smartphones. You can
create a push-enabled app with the Push API, net.rim.blackberry.api.push. The Push API listens for information in
the background and wakes up your app when new information arrives. Server-side functionality is provided in the
separately-downloaded Push SDK; see Push Service SDK development guides.
More information about characteristics and infrastructure
• BlackBerry Enterprise Server
Data storage APIs
There are several ways you can store, share, and manage data for your apps:
• 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
SQLite
database
Persistent store
Runtime store
Record store
Data format
Any
Relational
database file
Java® object
Java object
Serialized
Storage locations
Application
storage,
external media
card, built-in
media storage
External
media card,
built-in
media
storage
Application
storage
Application
storage
Application
storage
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
26
Features
File system
SQLite
database
Persistent store
Runtime store
Record store
Maximum storage
limit
Size of
partitions the
user has access
to
Size of
partitions
the user has
access to
Available
application
storage
Available
application
storage
Differs
according to
BlackBerry®
Device Software
version
BlackBerry Device
Software support
4.2 or later
(FileConnection
API)
5.0 or later
All
3.6 or later
All
Persists across
smartphone restarts
Yes
Yes
Yes
No
Yes
Applications can share
data
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 files
such as videos or large graphics.
• Memory on wireless smartphones can be very limited, so you should consider not storing all data on the
smartphone. BlackBerry® smartphones are frequently connected so your application can access data when
needed. In many cases, the best approach is to store data across smartphone restarts only for data that is
frequently 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 compatible
devices, you should consider a standards-based approach.
More information about data storage
• BlackBerry Java SDK Data Storage development guide
Multimedia API
The Multimedia API allows you to play and record audio and video. This API is the the Mobile Media API established
in JSR 135, and is provided in 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. Before
you 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.
27
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 a
String specifying the Control object that you require. You can find the available controls for your media player in
the javax.microedition.media.control package.
Before your application closes, you must invoke the Player object's close() method to deallocate any resources the
Player has created. You can also do this at any time to free up memory or resources. After you invoke close(), you
can no longer use the Player.
More information about multimedia
• Multimedia category overview
• BlackBerry Java SDK Multimedia developoment guide
Location-Based Services API
You 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 JSR
179 Location API in the javax.microedition.location package or the BlackBerry extensions to JSR 179 in the
net.rim.device.api.gps package.
• Geolocation: Provides location information using cell tower positioning and WLAN access points. You do not
require GPS technology on the smartphone to use the geolocation service. Geolocation is useful for applications
that require an approximate location and that can be used indoors (for example, applications that recommend
local 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), and
provides 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 UI
components. 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.
28
• 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 with
MapsArguments 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 selections
that you define. You can define the location picker dialog box with the Location Picker API, which is provided in the
net.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 given
time using the Travel Time API. Currently, the Travel Time API provides estimates only for automobile travel in the
United States and Canada.
To request a travel time estimate, retrieve an instance of the TravelTimeEstimator class. Use the
requestArrivalEstimate() method and specify the coordinates for the starting and ending locations, and the starting
time. The request is forwarded to a Travel Time server, which identifies a route between the starting and ending
locations and uses live and historical traffic information to calculate a travel time estimate. The estimate reflects the
known conditions on the specified date and at the specified time. The travel time estimate is returned by the
TravelTimeEstimator 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 areas
and receive notifications when a BlackBerry smartphone user enters or leaves the specified area. A geofence is a
virtual geographic area of interest that you can define by a radius around a location, or by coordinates that define a
polygon for the location.
Your application must instantiate a Geofence object and implement the GeofenceListener to receive notifications
for geofencing events (when a user enters or exits geofenced areas). Each instance of Geofence can process up to
20 monitored areas concurrently.
More information about LBS
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
29
• Location-Based Services category overview
• BlackBerry Java SDK Location-Based Services development guide
Security APIs
The 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 highly
secure connections, and manage cryptographic keys.
Secure Messaging API: The Secure Messaging API is an implementation of the CMS standard. CMS specifies standard
content types for cryptography. It describes message and transmission formats for those content types. S/MIME is
built on CMS. The net.rim.device.api.crypto.cms package provides classes to help you create and manage
CMS content types.
Secure Connection API: The Secure Connection API defines protocol functionality that you can use to establish highly
secure 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 of
HTTPS. 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 been
widely adopted. TLS is provided in the net.rim.device.api.crypto.tls package and the
net.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 WAP
involves using WTLS between the client smartphone and the WAP gateway, and one of SSL or TLS beyond the
WAP 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® smartphone
has a key store that is preloaded with root certificates for all of the certificate authorities. This practice makes it
possible for BlackBerry smartphone users to trust the root certificates, which form the basis for all subsequent chains
of 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 are
several 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.
30
Encoder API: Encoding is the process of converting data from one format to another. While it is often part of the
encryption process, encoding is not the same as encryption and is generally not secure. Keys are encoded to provide
a standard representation, not to protect their identity. Classes for encoding keys and signatures are provided in the
net.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 read
certificates 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 are
provided 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 be
possible even when data is encrypted and the smartphone is locked. Content protection encrypts data in such a way
that 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 everyBlackBerry smartphone. To use it, the smartphone must have
a 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 by
registering 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 data
that 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 decoding
data, registering listeners, and performing other tasks related to content protection.
• net.rim.device.api.system.PersistentContentListener: This listener interface lets your application receive
notifications 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 with
content protection.
BlackBerry® Balance™
BlackBerry® Enterprise Server administrators can set IT policy rules that distinguish work and personal information
on BlackBerry smartphones in their organization. You can use the Multiservice Platform API to implement BlackBerry
Balance features in your apps.
The net.rim.device.api.system.MultiServicePlatformManager class and the
net.rim.device.api.system.MultiServicePlatformListener interface allow you to implement controls on data access
and create listeners that allow administrators to delete data remotely. Modes (such as work) are defined in the
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
31
net.rim.device.api.system.ServiceMode class. The net.rim.device.api.system.Application class includes methods to
work with modes. The PL_INVALID_OPERATION exception is generated when an unauthorized, personal or non-work
application attempts to delete, create, read, or change a work file.
More information about security
• BlackBerry Java SDK Security development guide
• Cryptography category overview
• BlackBerry Java SDK Smart Card development guide
Support for Java ME APIs
The BlackBerry® Java® SDK includes Java® ME APIs as well as BlackBerry-specific APIs. Here is a summary of the
supported JSRs:
• 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.
32
Provide feedback
6
To 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.
33
Glossary
7
AES
Advanced Encryption Standard
BlackBerry transport layer encryption
BlackBerry transport layer encryption (formerly known as standard BlackBerry encryption) uses a symmetric key
encryption 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 environment
A BlackBerry® Enterprise Server environment consists of one or more BlackBerry Domain instances, a messaging
server, and any third-party software and hardware that the BlackBerry Enterprise Server components interact
with.
certificate
A certificate is a digital document that binds the identity and public key of a certificate subject. Each certificate
has a corresponding private key that is stored separately. A certificate authority signs the certificate to indicate
that it is authentic and can be trusted.
CLDC
Connected Limited Device Configuration
code-signing keys
Code-signing keys are the keys that are stored on media cards that sign files so that a user can install and run the
files on a BlackBerry device.
content protection
Content protection helps protect user data on a locked BlackBerry device by encrypting the user data using the
content protection key and ECC private key.
HTTPS
Hypertext Transfer Protocol over Secure Sockets Layer
IT policy
An IT policy consists of various IT policy rules that control the security features and behavior of BlackBerry
smartphones, BlackBerry® PlayBook™ tablets, the BlackBerry® Desktop Software, and the BlackBerry® Web
Desktop Manager.
IT policy rule
An 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.
34
Java® Development Kit
JVM
Java® Virtual Machine
Java ME
Java® Platform, Micro Edition
MIDP
Mobile Information Device Profile
PIM
personal information management
S/MIME
Secure Multipurpose Internet Mail Extensions
TCP/IP
Transmission Control Protocol/Internet Protocol (TCP/IP) is a set of communication protocols that is used to
transmit data over networks, such as the Internet.
WAP
Wireless Application Protocol
WTLS
Wireless Transport Layer Security
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
35
Document revision history
8
Date
Description
22 September 2011
Initial release
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
36
Legal notice
9
©2011 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, and related
trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the
U.S. and countries around the world.
Bluetooth is a trademark of Bluetooth SIG. Eclipse is a trademark of Eclipse Foundation, Inc. Facebook is a trademark
of Facebook, Inc. GSM is a trademark of the GSM MOU Association. Intel and Pentium are trademarks of Intel
Corporation. Java, JavaScript, and NetBeans are trademarks of Oracle America, Inc. OpenGL is a trademark of Silicon
Graphics, 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. All
other trademarks are the property of their respective owners.
This documentation including all documentation incorporated by reference herein such as documentation provided
or made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and
without condition, endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited
and its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or other
inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidential
information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized
terms. RIM reserves the right to periodically change information that is contained in this documentation; however,
RIM makes no commitment to provide any such changes, updates, enhancements, or other additions to this
documentation to you in a timely manner or at all.
This documentation might contain references to third-party sources of information, hardware or software, products
or services including components and content such as content protected by copyright and/or third-party web sites
(collectively the "Third Party Products and Services"). RIM does not control, and is not responsible for, any Third
Party Products and Services including, without limitation the content, accuracy, copyright compliance, compatibility,
performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products and Services. The
inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by
RIM of the Third Party Products and Services or the third party in any way.
EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS,
ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR
WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE
QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR
A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE
OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES
REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR
PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND
CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE
DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE
HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM
THAT IS THE SUBJECT OF THE CLAIM.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
37
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE
LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-
PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES
REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT,
CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES
FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS
OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO
TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH
RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION
THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES,
COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR
UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER
OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY
LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY.
THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE
CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT,
NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH
OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED
HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS
(INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE
PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.
IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE,
AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY
LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION.
Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure
that your airtime service provider has agreed to support all of their features. Some airtime service providers might
not offer Internet browsing functionality with a subscription to the BlackBerry® Internet Service. Check with your
service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party
Products and Services with RIM's products and services may require one or more patent, trademark, copyright, or
other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for
determining whether to use Third Party Products and Services and if any third party licenses are required to do so.
If required you are responsible for acquiring them. You should not install or use Third Party Products and Services
until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's
products and services are provided as a convenience to you and are provided "AS IS" with no express or implied
conditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability
whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to
you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except
to the extent expressly covered by a license or other agreement with RIM.
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
38
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 applicable
thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR
WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS
DOCUMENTATION.
Research In Motion Limited
295 Phillip Street
Waterloo, ON N2L 3W8
Canada
Research In Motion UK Limited
Centrum House
36 Station Road
Egham, Surrey TW20 9LF
United Kingdom
Published in Canada
RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.
39