Characteristics of BlackBerry devices
BlackBerry devices come in a variety of sizes, shapes, and capabilities. Among the currently available BlackBerry devices that might request your content, there is a range of software and hardware. The different hardware and software characteristics of BlackBerry devices have an impact on the user's browsing experience, and might influence the decisions you make as you create content for the BlackBerry Browser. BlackBerry devices can differ in the following ways: BlackBerry Device Software version screen size input methods, including the navigation method (trackwheel or trackball) and the keypad (QWERTY or SureType keypad)
The User-Agent header that accompanies every request from the BlackBerry Browser provides the BlackBerry device model number, from which you can determine the physical characteristics of the BlackBerry device, and the version of the BlackBerry Device Software that the requesting BlackBerry device is running.
BlackBerry Device Software version considerations
The BlackBerry Browser is a BlackBerry Device Software application that is included with every BlackBerry device. The version of the BlackBerry Device Software that is running on theBlackBerry device determines what content the BlackBerry Browser supports and how the content is rendered. Two generations of the BlackBerry Browser exist. The first generation of the BlackBerry Browser, included with BlackBerry Device Software version 4.5 or earlier, supports simple web page presentations and wireless-specific content very well. In BlackBerry Device Software version 3.8 or later, the BlackBerry Browser provides basic JavaScript and CSS support. In an effort to make more of the web accessible to the BlackBerry Browser, support for more complex presentation formats has been added over a number of releases. However, the first generation of the BlackBerry Browser focuses on managing and mitigating the effects of the wireless network. The second-generation BlackBerry Browser was introduced in BlackBerry Device Software version 4.6. The BlackBerry Browser rendering agent and JavaScript engine were completely redesigned to provide much greater support of existing web standards. With full support for standards such as HTML 4.01, CSS 2.1, and DOM Level 2, the second generation of the BlackBerry Browser has the ability to render most existing web content.
You should consider the BlackBerry Browser that is included with BlackBerry Device Software version 4.6 or later as functionally distinct from the first generation of the BlackBerry Browser that is included with earlier BlackBerry Device Software versions. When you design content for the BlackBerry device, you need to decide the version or versions of the BlackBerry Device Software to target. Keep in mind that the number of BlackBerry device users who use a first generation BlackBerry Browser to access your content is likely to be much larger than the number of users with a second generation of the browser. If you want to create content that makes use of the presentation and scripting support offered by the second generation of the BlackBerry Browser, consider also providing simplified content that targets BlackBerry device users who are browsing with a first generation of the BlackBerry Browser. For more specific information about what is supported with each version of the BlackBerry Device Software, see the BlackBerry Browser HTML Reference, the BlackBerry Browser CSS Reference and the BlackBerry Browser JavaScript Reference.

slide a finger to the left or right quickly on the screen hold a finger on an item
touch and drag an item on the screen
In a text field or in Month view in a calendar, this action moves the empty rectangle cursor in the same direction. touch the screen in two locations at the This action highlights the text between the two locations or the list of items, such same time as messages, between the two locations. To add or remove text or items from the selection, users can touch the screen at another location. press the Escape key This action cancels a selection. On a web page, map, or picture, this action zooms out one level. Users can press the Escape key twice to zoom back to the original view.

Keyboard

Users use the keyboard primarily to type text. On BlackBerry devices with a trackwheel or trackball, users can also use the keyboard to move around a screen (for example, to move around a map). However, navigation using the keyboard should always be an alternative to navigation using the trackball or trackwheel. BlackBerry devices with a trackwheel or trackball have either a QWERTY keyboard or SureType keyboard. Both types of keyboard include character keys and modifier keys. Character keys send a character to the BlackBerry device and include text keys, the Menu key, and the Escape key. A modifier key alters the functionality of character keys. Modifier keys include the Shift key and the Alt key.

QWERTY keyboard

The QWERTY keyboard provides users with a keyboard that is similar to the keyboard on a computer. Users type as they would on a computer keyboard except that numbers and symbols are located in different places.
To type common symbols, users press the Alt key and the appropriate character key. To type other symbols, users press the Symbol key. When users press a modifier key, a typing mode indicator appears in the upper-right corner of the screen.

SureType keyboard

BlackBerry devices with SureType technology integrate a traditional phone keypad and a familiar QWERTY-style keyboard with intuitive software. SureType technology is designed to predict words as users type them.

The BlackBerry MDS Connection Service is designed to provide users with secure access to their organization's intranets, and access to the Internet. The BlackBerry MDS Connection Service is a component of the BlackBerry Enterprise Server that exists on the organization's network behind a firewall. The BlackBerry MDS Connection Service acts as a proxy for the BlackBerry Browser, and makes requests on behalf of the BlackBerry Browser. The BlackBerry MDS Connection Service optimizes the content in the response, to enhance network efficiency and improve display on smaller screens, before it sends the content to the BlackBerry Browser. The BlackBerry Browser accesses the BlackBerry MDS Connection Service network gateway using the BlackBerry Browser configuration. The BlackBerry Browser configuration communicates with the BlackBerry MDS Connection Service using HTTP/ IPPP. To browse the Internet or an intranet through the BlackBerry MDS Connection Service network gateway, users must specify the BlackBerry Browser configuration in the Browser Configuration settings. Because the BlackBerry MDS Connection Service is a component of the BlackBerry Enterprise Server, administrators can specify a number of settings for the BlackBerry Browser configuration. For example, to help control the amount of bandwidth used, administrators can specify whether the BlackBerry Browser supports JavaScript.
BlackBerry MDS Connection Service security
To provide access to a requested web page, the BlackBerry MDS Connection Service opens a connection to the Internet from within the organization. The BlackBerry MDS Services can use SSL and TLS protocols to encrypt communication over the Internet between the BlackBerry Enterprise Server and the web server.
Communication between the BlackBerry MDS Connection Service and the BlackBerry Browserconfiguration is always encrypted with the same Triple DES that is used for all communication between the BlackBerry Enterprise Server and the BlackBerry device. The BlackBerry MDS Connection Service and the BlackBerry Browser configuration support HTTPS in the following modes: End-to-end mode: HTTP communication is encrypted using SSL or TLS for the entire connection between the BlackBerry device and the originating content server. Communication over the wireless network between the BlackBerry device and the BlackBerry MDS Connection Service is also encrypted using Triple DES encryption. Proxy mode: The BlackBerry MDS Connection Service performs SSL handshaking and sets up the SSL connection on behalf of the BlackBerry device. Communication over the wireless network between the BlackBerry device and the BlackBerry MDS Connection Service is not encrypted using SSL, but it is encrypted using Triple DES encryption. Communication over the Internet between the BlackBerry MDS Connection Service and the content server is encrypted using SSL or TLS. The BlackBerry MDS Connection Service network gateway supports several types of network authentication, including Basic authentication, NTLM, and Kerberos. To restrict wireless network access, administrators can turn the BlackBerry MDS Connection Service on or off for specific users or user groups. Administrators can also specify policies to control the organization's servers that users can access and the servers that can open push connections to the BlackBerry MDS Connection Service.

scripting

BlackBerry Browser features

Format type

Content type

Component

Partial support in BlackBerry Device Software version 4.2 4.2
Full support in BlackBerry Device Software version 4.2 3.7 3.8 3.7 3.7 3.7 3.2.1 3.2.1 4.3
WAV MIDI images animated GIF TIFF BMP JPEG PNG GIF web feeds RSS 0.9, 1.0, 2.0 RSS enclosures Atom
Category navigation Feature wireless service provider customizable bookmarks one-click link navigation bookmarks navigation history list cookie cache pushed content cache media streaming progressive image rendering page view column view offline form submission background downloading Included in BlackBerry Device Software version 3.8 3.7 3.2 3.2 3.2 3.6 4.3 4.2.2 4.2.1 3.2 3.8 3.2
content storage content rendering
wireless-friendly browsing

Network gateway features

Category usability
Feature single browser Home screen icon bookmarks associated with browser configurations
Included in BlackBerry Device Software version 4.2 4.2
Category Feature BlackBerry MDS Connection Service supported (4.2.2 or later) supported (4.1 or later) supported supported (3.6 or later) supported (3.6 or later) supported (4.1.5 or later) supported (3.7 or later) supported (3.7 or later) supported (3.6 or later) supported (3.2 or later) supported (3.2 or later) supported (3.2 or later) supported (3.2 or later) BlackBerry Internet Service Browsing supported supported supported supported supported supported supported supported WAP

content delivery

content optimization

security

progressive delivery browser session management PAP push applications RIM push applications web signal push applications WAP push applications image optimization enhanced image optimization content filtering content preprocessing SSL/TLS encryption WTLS encryption Triple DES encryption Kerberos authentication NTLM authentication Password authentication protocol RADIUS for PDP web access restriction
supported supported supported supported
Content and network management in the BlackBerry Browser

Content rendering

Browser content views
The BlackBerry Browser can display content in Column View or Page View. In BlackBerry Device Software version 4.5 or earlier, Column View is the default view. In BlackBerry Device Software version 4.6 or later, Page View is the default view. View Column View Description In Column View, content is rendered vertically in a column the width of the screen. Content that exceeds the width of the column is wrapped. Table rows that extend beyond the width of the screen are wrapped, with the excess table cells displayed immediately below. On devices in which framesets are supported, the frameset layout is ignored. Instead, the BlackBerry Browser displays the content of each frame vertically in the order in which they are encountered. Page View was introduced in BlackBerry Device Software version 4.2.1, for BlackBerrydevices with a trackball. Page View renders pages on a 1024 x 768 pixel canvas, appropriate for displaying content designed for desktop computers, and scales the content to fit the width of the screen. Users can scroll to the area of interest and zoom in to view the content at a standard size. When zoomed, the content exceeds the width of the screen; users must scroll horizontally to view all of the content. Page View is designed to display desktop-focused content in the BlackBerry Browser window. Content that is designed specifically for the BlackBerry Browser should not be displayed in Page View. To control how the content displays on the device, the BlackBerry Browser supports the HandheldFriendly and viewport <meta> tags. To ensure that the content that is designed for the BlackBerry Browser is displayed correctly, you must add one of the following tags to the <head> element of your HTML content: <meta name="HandheldFriendly" content="true" > <meta name="viewport" content="width=device-width" >

Page View

Style sheets and CSS support
The BlackBerry Browser supports inline, internal, or external CSS style definitions. The level of support for style sheets in the BlackBerry Browser depends on the version of BlackBerry Device Software that the BlackBerry device is running. BlackBerry Device Software version 3.8 to 4.5
Description In BlackBerry Device Software version 3.8 to 4.5, the BlackBerry Browser provides partial support for WAP CSS. The BlackBerry Browser supports the following CSS models: Box model Border properties (introduced in BlackBerry Device Software version 3.8) Padding properties (introduced in BlackBerry Device Software version 4.3) Colors and background Fonts (excluding font-variant) Positioning The height and width properties (introduced in BlackBerry Device Software version 3.8) Text (text-align, text-decoration properties only) WAP marquee extensions WAP input extensions

4.6 or later

In BlackBerry Device Software version 4.5 or earlier, users can turn off support for style sheets in the BlackBerry Browser options, which prevents the BlackBerry Browser from processing any style data, whether inline, internal, or external. In BlackBerry Device Software version 4.6, the BlackBerry Browser provides full support for CSS 2.1, excluding pseudo-elements and dynamic pseudo-classes, system fonts, and generated content. The BlackBerry Browser supports the following CSS models: Box model Border properties Margin properties
BlackBerry Device Software version
Description Padding properties
Colors and background Fonts Lists Positioning Text Visual effects WAP input extensions
With enhanced CSS support and access to the DOM using JavaScript, the BlackBerry Browser supports most dynamic HTML effects, such as hiding or displaying web page content dynamically. In BlackBerry Device Software version 4.6 or later, users can not specify support for style sheets; style sheets are always supported. For a complete list of the supported CSS properties and the BlackBerry Device Software version in which support was introduced, see the BlackBerry Browser CSS Reference.

Form support

Forms work very well in the BlackBerry Browser. Entering text is very simple on BlackBerry devices, and users can easily navigate through the form with any of the navigation methods available on BlackBerry devices. On BlackBerry devices with a trackball, users can position the cursor over the form control. Users must click the trackball to activate the form control that has focus. On BlackBerry devices with a trackwheel, users can use the trackwheel to skip sequentially through the form controls. Users must click the trackwheel to activate the form control that has focus.
The level of support for forms in the BlackBerry Browser depends on the version of the BlackBerry Device Software that the BlackBerry device is running.

BlackBerry Device Software version 3.7 to 4.5
Description In BlackBerry Device Software version 3.7 to 4.5, the BlackBerry Browser provides supports for basic form elements, including partial support for the <form>, <input>, <select>, <textarea>, and <option> elements. Support for <optgroup> is available in version 3.8 or later. As of BlackBerry Device Software version 4.2, all input types are supported. In earlier versions, <input type="file"> is not supported. Support for JavaScript version 1.5 is available in BlackBerry Device Software versions 3.8 to 4.5. You can create simple scripts to perform some client-side validation of form fields. In BlackBerry Device Software version 4.6 or later, the BlackBerry Browser provides full support for forms. Support was introduced in BlackBerry Device Software version 4.6 for the following elements: <button> <fieldset> <label> <legend> With full DOM Level 2 and JavaScript support, any type of client-side form validation is possible.

Table support

The level of support for tables in the BlackBerry Browser depends on the version of the BlackBerry Device Software that the BlackBerry device is running. BlackBerry Device Software Description version 3.7 or earlier 3.8 to 4.5 Tables are not supported in the BlackBerry Browser in BlackBerry Device Software version 3.7 or earlier. In BlackBerry Device Software versions 3.8 to 4.5, the BlackBerry Browser provides basic support for tables, including support for the <table>, <tr>, <td>, and <th> elements.
BlackBerry Device Software Description version Basic layout attributes for tables are supported. You can span rows and columns or adjust padding or spacing between table cells. Content in table cells is always wrapped; the nowrap attribute is not supported. In BlackBerry Device Software version 4.5 or earlier, users can turn off support for tables in the BlackBerry Browser options. In BlackBerry Device Software version 4.6 or later, the BlackBerry Browser provides full support for tables, including support for the <thead>, <tbody>, and <tfoot> container elements. In BlackBerry Device Software version 4.6 or later, users can not specify support for tables; tables are always supported. The view that the user specifies has an impact on how tables appear on the BlackBerry device. In Column View, table rows that exceed the width of the device screen wrap to fit the width of the screen, and the row cells are stacked vertically. In BlackBerry Device Software version 4.6 or later, the BlackBerry Browser ignores table layout in Column View. Each table cell is rendered on a new line. In Page View, tables are rendered as defined. Users might be required to scroll horizontally to view the entire width of the table.

Page navigation

Users can navigate through web pages in the BlackBerry Browser differently depending on the BlackBerry device's input methods. The BlackBerry Browser also includes shortcut keys for navigation operations. Input method trackwheel Description The trackwheel is primarily designed to scroll vertically. To scroll horizontally, the BlackBerry device user must press the Alt key while they roll the trackwheel.

Input method

Description When the user rolls the trackwheel, the focus on the page moves from link to link.

trackball

To follow a link, the user clicks the trackwheel. The trackball is designed to provide two-dimensional navigation, similar to desktop browsers. The trackball controls a cursor that appears on the screen. When the user rolls the cursor over a link, the cursor image changes to indicate a clickable area. To follow a link, the user clicks the trackball.

Link behavior

The BlackBerry Browser identifies links using a dotted underline if no styles are applied, or if the user turns off style sheet support. To follow links, users can click the trackball or trackwheel, or highlight the link and click the Get Link menu item. The BlackBerry Browser can create links that can integrate with other BlackBerry device applications. When the BlackBerry Browser renders the content, it scans the content for patterns that appear to be telephone numbers or email addresses, and creates links that will open the phone or email application. If necessary, you can override this behavior by adding the following meta tag to your document: <meta http-equiv="x-rim-auto-match" content="none"> The BlackBerry Browser supports the following link types: Link type web page links image maps Description On a web page, users scroll to links by rolling the trackball or trackwheel. In the BlackBerry Browser, hotspot regions within the image are denoted with a dotted line. On BlackBerry devices with a trackwheel users can navigate from link to link within the image. When the appropriate hotspot is selected, users can click the trackwheel to follow the link. On BlackBerry devices with a trackball users can move the cursor to the hotspot and click the trackball to follow the link.

phone links

The BlackBerry Browser supports the following types of phone links: WTAI Make Call links (URI form): <a href="wtai://wp/mc;14165551212">Call office</a>

Link type

Description phone links in I-mode format: <a href="tel:14165551212">Call office</a> Direct Connect links on iDEN networks: <a href="dc:234*234*234">Call office</a> CTI: <a href="cti:333333">Call office</a> When users click a phone link, the phone application opens and users are prompted to confirm whether or not to proceed with the call. The BlackBerry Browser supports the following types of email links: standard email mailto: format: <a href="mailto:jane.doe@blackberry.com">Email Jane</a> PIN messaging: <a href="PIN:1234a567">send pin message to Jane</a> When users click an email link, the Compose Email dialog box appears and users are prompted to confirm whether or not to proceed.

email links

Navigation history in the BlackBerry Browser
The BlackBerry Browser maintains a list of recently visited web pages. When the user navigates to a web page, the browser adds the URL of that web page to the navigation history list. In BlackBerry Device Software version 4.3 or later, the BlackBerry Browser implements the navigation history in a dedicated history page in which recently viewed web pages are organized by date and domain. In earlier versions, visited web pages are listed chronologically from most recent to oldest. When the navigation history list reaches the maximum number of items, the browser replaces the earliest pages with the new URLs. When the user navigates back to a previous page and selects a new link from that page, the browser removes any URLs after that web page in the history list and the URL of the selected page becomes the last item in the navigation history list. Items in the navigation history list might be removed for the following reasons: If memory on the device is low, the browser removes items from the navigation history list to free memory. Users might delete items from the list. Users can delete a single item in the navigation history list, all items for a domain, or all items for a day. Users can clear the navigation history list using the BlackBerry Browser Cache Options.

Content storage

If a user does not use a predefined link to navigate to a WML page (for example, the user does not use a bookmark or the Go To dialog box), or if a WML page has a newcontext attribute defined, the browser clears the navigation history list before it displays the WML page. This behavior is required to conform to WML security specifications.
The web pages that are listed in the navigation history list are specific to the browser configuration in which the user viewed the web pages. When the browser displays web pages from the history, the browser uses the same browser configuration in which the web pages were originally displayed. For example, if the user visits a web page using the Internet Browser configuration, then visits a second web page using the WAP browser configuration, if the user navigates back to the first web page, the browser uses the Internet Browser configuration to display the web page.

Content optimization and delivery
Content optimization by the network gateway
The BlackBerry MDS Connection Service and the BlackBerry Internet Service Browsing network gateways are specifically designed to deliver content to the BlackBerry Browser. To help maximize efficiency and minimize the bandwidth requirements of content that is sent over the wireless network, these network gateways use optimization techniques unique to the BlackBerry Infrastructure. The BlackBerry MDS Connection Service and the BlackBerry Internet Service Browsing network gateways optimize content in the following ways: by reading the existing content in the BlackBerry Browser cache to determine if requested content is already stored on the device by preprocessing requested content and filtering out unsupported or unnecessary markup or resources by converting images into an appropriate format for display on the BlackBerry device, reducing the color depth of images, and scaling images for display on a small screen size by compressing content for efficient delivery over the wireless network
Some WAP network gateways might optimize content and might convert HTML to XHTML or limit the size of images. WAP network gateways are not designed for a particular user agent, and therefore cannot offer the same level of optimization for the BlackBerry Browser as the BlackBerry MDS Connection Service or the BlackBerry Internet Service Browsing network gateways. Content delivery times are typically slower over WAP network gateways. WAP network gateways do not remove unsupported elements before they send the content. As a result, the BlackBerry Browser must parse more content on the BlackBerry device, which increases the time it takes to render the content.

Content transcoding

The BlackBerry MDS Connection Service and BlackBerry Internet Service Browsing network gateways transcode data into formats that are more suitable for sending over the wireless network and for rendering in the BlackBerry Browser. Data type markup languages Description Markup languages are transcoded in the following ways: HTML and XHTML are simplified and transcoded into a format similar to WBXML. WML is transcoded into WMLC. SVG is transcoded into PME, a proprietary binary file format that BlackBerry devices can render.

Data type scripts images

Description JavaScript (internal or external) is transcoded into JavaScript bytecode. WMLScript is transcoded into compiled WMLScript. All.gif files are transcoded into.png file format. If the BlackBerry device does not support native.jpg files,.jpg files are converted to.png file format. JAR files are converted into.cod file format.

image color depth

Enhanced image optimization is included in the BlackBerry MDS Connection Service network gateway (version 4.1.3 or later) and the BlackBerry Internet Service Browsing network gateway. Enhanced image optimization is designed to provide an additional 15 to 20% size reduction. Higher quality images can be sent to the BlackBerry device without an increase in the use of bandwidth. Enhanced image optimization applies only to GIF, PNG, and JPEG image formats. Users with BlackBerry devices running BlackBerry Device Software version 4.2.1 or later can specify the level of quality as low, medium, or high for images sent to the BlackBerry device. For BlackBerry devices running earlier versions of the BlackBerry Device Software, the network gateway sets the image quality as medium.
Progressive downloading of images
The BlackBerry MDS Connection Service network gateway (version 4.1.3 or later) and the BlackBerry Internet Service Browsing network gateway support progressive downloading of images. When the network gateway compresses an image, it also divides the file into segments. It sends the file segments to the BlackBerry Browser incrementally. As the web page is rendered in the BlackBerry Browser, low quality placeholder versions of the images render quickly. After the entire page is rendered, the browser receives the additional image file segments. As the additional file segments arrive, the placeholder images are enhanced until the images meet the image quality that is specified by the user.
You can notify users that new content is available or, depending on the network gateway, you can push new content directly to the BlackBerry device. The level of support for pushing content depends on the network gateway. BlackBerry MDS Connection Service: Among the three network gateways, the BlackBerry MDS Connection Service offers the most support for pushed content delivery. Content is pushed directly to the BlackBerrydevice and is stored in a dedicated cache for pushed content. You can develop the push service to place an icon on the Home screen (the icon changes to notify the user of new content), to send the content to the message list (that appears like any other message), or to deliver the content directly to the cache without any user notification. When the user next views the content, it is available on the BlackBerry device; the user does not need to download it.
BlackBerry Internet Service Browsing: The BlackBerry Internet Service Browsing network gateway supports pushed content delivery. Content is pushed to the BlackBerrydevice through web signals using a push/pull architecture. You can develop a web signal to place an icon on the Home screen. The icon changes to notify the user that new content is available, prompting the user to download the content. WAP network gateways: WAP network gateways support pushed content delivery, typically of SMS or UDP messages, depending on the network. To support pushed content delivery through WAP network gateways, the WAP Push service record must be provisioned on the BlackBerrydevice. WAP Push service records are typically provisioned when a BlackBerrydevice is registered with the wireless service provider.

Pushed content supported by the BlackBerry MDS Connection Service
The BlackBerry MDS Connection Service is designed to provide extensive support for pushing content or data to BlackBerry devices. To push content to the BlackBerry device, you can develop server-side applications that make HTTP POST requests to the BlackBerry MDS Connection Service. Requests include a list of the destination BlackBerry devices that are targeted to receive the pushed content. The BlackBerry MDS Connection Service sends the content to the appropriate BlackBerry devices using the users' email addresses. The BlackBerry MDS Connection Service manages the connection to the wireless network and verifies that content is delivered as soon as a user is in a wireless coverage area. On the BlackBerry device, a separate browser listener thread listens on port 7874 for incoming messages and processes incoming messages. The BlackBerry MDS Connection Service supports the following content push protocols: Content push protocol RIM Push Description The RIM Push protocol sends the content as a byte stream to the destination BlackBerry device to the port that is specified in the URL of the pushed message. Pushed data can be stored in RAM on the BlackBerry MDS Connection Service server or in the BlackBerry Enterprise Server database. The PAP protocol sends an HTTP POST request containing a PAP message. The message is a MIME multipart message that includes the control entity and the pushed content. The control entity is an XML document that specifies information about the destination BlackBerry device address, message ID, delivery time stamps, and so on.

WAP PAP Push

Supported push methods
Using the BlackBerry MDS Connection Service, you can push content to the BlackBerry device using any of the following push methods:
Pushing content to a browser channel: This method delivers content to the browser cache and adds an icon on the Home screen as entry point to the content. Clicking the icon opens the pushed content in the browser. Pushing content to the message list: This method delivers content to the message list, where it appears as an item in the list. Clicking the item in the message list displays the pushed content in the browser. Pushing content to the browser cache: This method delivers content to the cache, but provides no notification to the user. The next time the user accesses the content, the updated cached content is displayed.
The default amount of time that pushed content is stored in cache memory depends on the version of the BlackBerry Device Software is running on the device. In BlackBerry Device Software version 3.8 or later, pushed content is cleared from the cache after 12 hours. On devices running an earlier version of the BlackBerry Device Software, pushed content expires and is cleared from the cache after 29 days. To increase or decrease the time content is stored in cache memory, you can specify a date and time in the HTTP header of the push request with the Expires header. For example, the following header will store content in cache until December 31, 2018 at 12PM GMT. Expires: Wed, 31 Dec 2018 24:00:00 GMT Content might be cleared from the cache prior to the value specified in the Expires header. If the BlackBerry device runs low on flash memory, the browser cache might be cleared to free up space, or the user might choose to manually clear the pushed content cache.

Pushed content supported by the BlackBerry Internet Service Browsing network gateway
You can push content to BlackBerry device users through the BlackBerry Internet Service Browsing network gateway by creating web signals. Web signals enable you to push content to the BlackBerry Browser using the BlackBerry Internet Service Browsing as the network gateway. Users subscribe to the web signal(s) you offer and receive an icon on their Home screen. To the user, the web signal appears like any other application. When they click the web signal icon, the Internet Browser configuration opens and retrieves the content through the BlackBerry Internet Service Browsing. To push content to users, you must first register one or more web signals with Research In Motion. Users can subscribe to receive your web signal(s) on their BlackBerry devices. Creating content for a web signal can be simple or complex. At its simplest, a web signal requires a subscription web page, two icons used to identify the web signal on the BlackBerry device Home screen (the standard icon, displayed when no new content is available, and the other notification icon, displayed when new content is available), and a web page that contains the content that subscribed users can view. When you want to alert web signal subscribers to new content, you can submit an HTTP POST request to the BlackBerry Infrastructure. A parameter in the POST request lists the subscribed users to whom the URLs should be sent. The BlackBerry Infrastructure receives the request and queues it, then delivers the URLs of the icons and the content to the BlackBerry devices.
The BlackBerry Browser retrieves the icons without user intervention, and replaces the standard icon with the notification icon on the Home screen. When the user clicks the notification icon, the BlackBerry Browser opens and retrieves the content from the URL specified in the push request. After the user clicks the notification icon, the BlackBerry Browser replaces the notification icon with the standard icon on the Home screen.
Pushed content supported by WAP network gateways
To push content through a WAP gateway, a WAP Push service record must be provisioned on the BlackBerry device. WAP Push service records are typically sent during registration. On the BlackBerry device, the WAP Push service record specifies how the BlackBerry device receives WAP pushes, on which ports the WAP Push Processor listens for incoming WAP Push messages, and how the BlackBerrydevice manages the incoming messages. Server applications can push content to the BlackBerry device using one of the following methods: Existing WAP connections: This method is available only when a WAP connection is open between the BlackBerry device and the WAP gateway. SMS messages: If an existing WAP connection is not available, the service record provisioned for the GPRS and CDMA networks typically uses SMS. Wireless service providers can restrict incoming SMS messages to specific source addresses. The source address restrictions are specified as parameters in the WAP Push service record. UDP messages: If an existing WAP connection is not available, the service record provisioned for the iDEN network typically uses UDP. Push message types service indicator Description These messages are self-contained with some text to inform the user about an event or notification. The entire text of the message is included in the service indicator that is pushed to the BlackBerry device. These messages include a URL at which the new content is located. The service loading message is pushed to the BlackBerry device first, and then the browser automatically downloads content from the URL location.

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

BlackBerry Java Development Environment

Version: 4.7.0

Fundamentals Guide
SWDT499912-499912-1212115921-001

Contents

1 Understanding BlackBerry and programming for BlackBerry devices... Design principles for BlackBerry devices..... Release cycles and versions..... BlackBerry Java Development Environment..... Java ME and Java APIs for BlackBerry..... Support for standard Java APIs..... Support for Java API extensions.... BlackBerry solutions...... BlackBerry Enterprise Solution..... BlackBerry Internet Service..... BlackBerry MDS...... 21 22
2 BlackBerry Java Application design..... Standalone applications...... Applications with desktop synchronization.... Applications with wireless access, wireless synchronization, or wireless alerting... MIDlet applications..... CLDC applications..... API control and code signing..... Object modeling...... Multithreading...... Best practice: Using multithreading.... Best practices for writing an efficient BlackBerry Java Application.... Best practice: Writing efficient code.... Best practice: Using objects judiciously.... Best practice: Reducing the size of compiled code... Multilanguage support..... Best practice: Storing text strings in resource files... Multimedia support...... Audio support..... Imaging support..... Video support..... 3 UI and navigation design.....
BlackBerry device user input and navigation.... Trackwheel versus Trackball..... Creating a UI that is consistent with standard BlackBerry UIs.... 4 Memory management...... Managing memory..... BlackBerry device memory..... Key resources to reserve..... Best practice: Minimizing memory use..... Managing low memory availability..... Identifying low memory availability on a BlackBerry device... Conserving resources..... Best practice: Using efficient data structure selection.... Best practice: Consolidating objects into object groups.... Garbage collection on a BlackBerry device.... RAM garbage collection on a BlackBerry device.... Full garbage collection on a BlackBerry device.... Idle garbage collection on a BlackBerry device.... 5 Data management...... Support for APIs to store data to persistent memory..... Persistent Store APIs..... MIDP Record management system APIs..... File Connections APIs..... Storage on removable media..... Accessing data on the microSD media card.... Backing up and synchronizing data..... 6 Wireless data transport...... Wireless gateways...... Using the BlackBerry Enterprise Server as an network gateway... Using the wireless service provider's Internet gateway.... Alternative data transport options.... Using email to transport data..... Using SMS to transport data.... Using PIN messaging to transport data....
7 BlackBerry application integration.... Adding custom menu items..... Integrating with BlackBerry Device Software applications... Accessing email and organizer data..... Using BlackBerry Messenger with a BlackBerry Application.... Using listeners to respond to application changes.... 8 Security considerations..... Data encryption and the BlackBerry Application.... Data encryption in transport..... Data encryption on the BlackBerry device.... Access to memory...... Authentication...... BlackBerry device authentication and IT policy.... Application authentication..... Server-side authentication..... Controlled APIs and code signing..... BlackBerry APIs with controlled access..... IT policy support...... Application control..... File encryption on microSD cards..... Encryption of data on a microSD media card.... Using the microSD media card with more than one BlackBerry device... IT policies and the microSD media card.... 9 Test a BlackBerry Java Application.... Obfuscating a BlackBerry Java Application.... Preverifying a BlackBerry Java Application..... Testing applications on a BlackBerry Smartphone Simulator.... Testing applications on a BlackBerry device.... BlackBerry simulators..... BlackBerry Smartphone Simulator..... BlackBerry MDS Simulator..... BlackBerry Email Simulator.....
10 Making applications available..... Application distribution through a computer connection.... Distribute an application from a computer.... Distribute an application from a web page.... Distribute an application for testing.... Application distribution over the wireless network.... Wireless pull (user-initiated)..... Wireless push (server-initiated)..... 11 Glossary....... 12 Legal notice......
Understanding BlackBerry and programming for BlackBerry devices
BlackBerry devices provide a Java ME wireless environment that supports client/server applications. Application developers can create a BlackBerry Java Application that has sophisticated UIs for data entry and searching, and that supports multithreading, internationalization, network communication, and local data storage. Applications can communicate with networks using standard TCP and HTTP connections, regardless of the underlying wireless network. Application developers can also create a BlackBerry Java Application that integrates tightly with core BlackBerry device applications, such as the message list, organizer applications, phone, and browser, for an essentially seamless user experience.

The BlackBerry Java Development Environmentis a fully integrated development and simulation environment for building a BlackBerry Java Application for BlackBerry devices. With the BlackBerry JDE, developers can build applications using the Java ME programming language and the extended Java APIs for BlackBerry. The BlackBerry Java Development Environment includes the following development tools: BlackBerry Integrated Development Environment BlackBerry Smartphone Simulator Java ME APIs and BlackBerry APIs sample applications
The BlackBerry IDE includes a full suite of editing and debugging tools that are optimized for the development of a BlackBerry Java Application. TheBlackBerry Smartphone Simulator provides a complete Windows type environment, and is designed to simulate UIs and user interaction, network connections, email services, and wireless data synchronization.
Java ME and Java APIs for BlackBerry
The BlackBerry Java Development Environment Component Package includes the following development tools for development within third-party IDEs such as NetBeans or Eclipse: RAPC: You can use this command prompt compiler to compile.java and.jar files into.cod files that you can run in the BlackBerry Smartphone Simulator or on a BlackBerry device. JavaLoader: You can use this tool to add or update an application on a BlackBerry device 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 BlackBerry device. JDWP: You can use this tool to debug applications using third-party integrated development environments.
Java ME is an industry standard platform that defines common sets of Java APIs for different types of wireless and embedded devices. A Java ME application on a BlackBerry device runs in the BlackBerry Java Virtual Machine, which provides all of the runtime services to the applications and performs functions such as typical memory allocations, security checks, and garbage collection. The Java ME MIDP standard addresses the API and BlackBerry JVM needs of a constrained wireless device with a user interface. The BlackBerry device supports the Java ME MIDP standard as defined in JSR 118. The Java MEMIDP standard provides a core set of Java APIs that any BlackBerry device can support, regardless of its underlying operating system. Developers can often build one Java application using the MIDP standard APIs and run that application on many different types of devices.

Support for standard Java APIs
The BlackBerry device and the BlackBerry Java Development Environment support the Java ME MIDP standard, which provides a core set of Java APIs that you can use to develop wireless device applications. The BlackBerry device and the BlackBerry Java Development Environment also support the following JSRs: JSR 30: Connected Limited Device Configuration Version 1.0 (supported on devices with BlackBerry Device Software version 4.0 or earlier) JSR 37: Mobile Information Device Profile Version 1.0 (supported on devices with BlackBerry Device Software Version 4.0 or earlier) JSR 75: Portable Optional Packages for the J2ME Platform (PDAP) support for the PIM APIs only and the File Connection API for Java ME (supported on devices with BlackBerry Device Software version 4.2 or later) JSR 82: Java APIs for Bluetooth JSR 118: Mobile Information Device Profile Version 2.0 JSR 120: Wireless Messaging API (WMA) Version 1.1 JSR 135: Mobile Media APIs (MM API) Version 1.1

BlackBerry solutions

JSR 139: Connected Limited Device Configuration Version 1.1 JSR 172: J2ME Web Services JSR 177: Security and Trust Services API for J2ME (SATSA) JSR 179: Location API for Java ME JSR 185: Java Technology for the Wireless Industry (JTWI) JSR 205: Wireless Messaging API 2.0 JSR 211: Content Handler API JSR 226: Scalable 2D Vector Graphics API for Java ME JSR 238: Mobile Internationalization API
Support for Java API extensions
BlackBerry devices support the following Java APIs that are not part of the standard JSR definitions and that can provide greater features and functionality over what is available in the standard MIDP API libraries. API User Interface APIs Persistent Data Storage APIs Networking and I/O APIs Event Listeners Application Integration APIs Additional Utilities Description You can use these APIs to create screens, menu items, and all the components of the user interface. You can use these APIs to store custom data locally within your application. You can use these APIs to establish network connections and read or write data to a server-side application. You can use the Event Listeners to respond to BlackBerry device user or systeminitiated events on a BlackBerry device. You can use these APIs to integrate with the existing BlackBerry email, phone, calendar, contacts, browser, camera, media player, and task list applications. You can use these additional APIs for data encryption and compression, XML parsing, Bluetooth connectivity, location-based services, and so on.

You can use the BlackBerry APIs to build applications with desktop synchronization capabilities, such as reference guides and organizer applications. The user connects the BlackBerry device to a computer to manage and synchronize data that is located on the computer. Research In Motion does not provide HotSync conduits or any other direct database synchronization module. You must build the synchronization code, and the BlackBerry device user must initiate the data synchronization process manually. After the application is installed on the BlackBerry device, the BlackBerry device user must synchronize information manually by connecting their BlackBerry device to the computer with a serial connection, a USB connection, or a Bluetooth connection.
Applications with wireless access, wireless synchronization, or wireless alerting
You can use the BlackBerry APIs to build applications that push content proactively over the wireless network to BlackBerry devices in environments that use the BlackBerry Enterprise Server. A BlackBerry Java Application for BlackBerry devices uses a wireless connection to the Internet or the corporate intranet to provide BlackBerry device users with access to remote data and applications. The BlackBerry Java Development Environment provides APIs you can use in applications to establish network connections to servers on the Internet or the corporate intranet.

MIDlet applications

The MIDlet application model is part of the MIDP specification. The main class of a MIDlet always extends the MIDlet class and it must use methods for startApp(), pauseApp(), and destroyApp().

CLDC applications

Advantages
Disadvantages Applications can use only the user interface APIs that exist in the javax.microedition.lcdui library. The model assumes that all application processes terminate when the application closes. Applications cannot start automatically in the background when the device turns on.
Applications are portable to other devices that also support the MIDP specification.
The CLDC application model is a specification of a framework for Java ME. A CLDC application extends the UiApplication class and starts with a standard main() method. Most of the sample applications that the BlackBerry Java Development Environmentincludes use the CLDC application model. All of the core BlackBerry applications (including message list, contacts list, calendar, and the browser) are built as CLDC applications. Advantages BlackBerry User Interface APIs provide more functionality and flexibility than the standard javax.microedition.lcdui library. Applications can run active background threads after they have closed. Applications can start automatically in the background when the device turns on. Applications can use IPC APIs to exchange information with other applications. Developers can create reusable library modules that CLDC applications can import. Disadvantages Applications are not portable to other devices.

Using local variables

Use local variables whenever possible. Access to local variables is more efficient than access to class members.
Using shorthand for evaluating Boolean conditions
To evaluate a Boolean condition, use shorthand. The resulting compiled code is shorter. Code sample return( boolean_expression );

Making classes final

When you create code libraries, mark classes as final if you know that developers will never extend them. The presence of the final keyword allows the compiler to generate more efficient code. By default, the BlackBerry Java Development Environment compiler marks any classes that you do not extend in an application.cod file as final.
Using int instead of long
In Java, a long is a 64-bit integer. Because BlackBerry devices use a 32-bit processor, operations can run two to four times faster if you use an int instead of a long.
Avoiding garbage collection
Avoid calling System.gc() to perform a garbage collection operation because it might take too much time on BlackBerry devices with limited available memory. Let the BlackBerry Java Virtual Machine collect garbage.
Using static variables for Strings
When you define static fields (also called class fields) of type String, you can increase application speed by using static variables (not final) instead of constants (final). The opposite is true for primitive data types, such as int. For example, you might create a String object as follows: private static final String x ="example"; For this static constant (denoted by the final keyword), each time that you use the constant, a temporary String instance is created. The compiler eliminates "x" and replaces it with the string "example" in the bytecode, so that the BlackBerry Java Virtual Machine performs a hash table lookup each time that you reference "x". In contrast, for a static variable (no final keyword), the String is created once. The BlackBerry JVM performs the hash table lookup only when it initializes "x" , so access is faster. private static String x = "example"; You can use public constants (that is, final fields), but you must mark variables as private.
Avoiding the String(String) constructor
In a BlackBerry Java Application, each quoted string is an instance of the java.lang.String class. Create a String without using the java.lang.String(String) constructor.
Code sample String str = "abc"; String str = "found " + n + " items";

Writing efficient loops

If your container is likely to contain more than one element, assign the size to a local variable. If the order in which you iterate through items is not important, you can iterate backward to avoid the extra local variable on the stack and to make the comparison faster. Code sample int size = vector.size(); for( int i = 0; i < size; ++i ) {. } for( int i = vector.size() - 1; i >= 0; --i ) {. }

Best practice: Storing text strings in resource files
Instead of using text in source code, design applications to use resource files for localization (adapt to specific languages and regions). Consider the following guidelines: Store the text strings for each locale in a single resource file. In your source code, use unique identifiers to make use of the appropriate resource files. Design the application to dynamically retrieve the appropriate resource file to display to the BlackBerry device user based on the locale of the BlackBerry device user.

Multimedia support

Audio support
You can create a BlackBerry Java Application that works with the audio formats that a BlackBerry device supports. The type of audio format that a BlackBerry device supports depends on the BlackBerry device model number. For more information about audio support on a BlackBerry device, visit www.blackberry.com/developers.

Imaging support

On a BlackBerry device that includes a camera, when a BlackBerry device user takes a picture, the BlackBerry device stores the picture in the file system on the BlackBerry device. A BlackBerry Java Application can access the pictures by using the File Connection API for Java ME that is available in BlackBerry Java Development Environment version 4.2 or later. The BlackBerry Java Application can invoke the camera application and listen for events when images are added to the file system.

Video support

You can create a BlackBerry Java Application that displays images and uses the graphics API classes to work with multimedia content to play a video file on BlackBerry devices that include an integrated media player.

UI and navigation design

BlackBerry device user input and navigation
BlackBerry devices include a keyboard, a trackwheel or trackball, and an Escape key, for input and navigation. The Escape key provides an easy way for BlackBerry device users to go back to the previous screen or remove a menu or dialog box from the screen. A BlackBerry Java Application for BlackBerry devices should use the following input and navigation model as closely as possible. Clicking the trackwheel or trackball typically invokes a menu. Pressing the Escape key changes the display to the previous screen or closes the application from the main screen.
By default, the BlackBerry screen objects provide this functionality without customization; however, you must add menu items and additional UI and navigation logic.
Trackwheel versus Trackball

Trackball sensitivity

Trackball sensitivity refers to the amount of trackball movement that is required for the system to identify the movement as a navigation event, and to dispatch a navigation event to the software layer. The BlackBerry device hardware measures physical trackball movement using units called ticks. When the number of ticks along an axis surpasses the threshold of the system or a BlackBerry Java Application, a navigation event along that axis is dispatched to the software layer, and the system resets the tick count to zero. Tick counts are also reset to zero after a certain amount of idle time passes. You can use the TrackBall API to set the trackball sensitivity. High trackball sensitivity equates to a smaller tick threshold, which means that small trackball movements will trigger navigation events. Conversely, low trackball sensitivity equates to a larger tick threshold, which means that larger trackball movements are required to generate navigation events.

Memory management

Managing memory
The BlackBerry Java Virtual Machine manages memory usage on the BlackBerry device. The BlackBerry JVM allocates memory, performs garbage collection, and automatically swaps data between SRAM and flash memory. The BlackBerry JVM must also share available memory between the BlackBerry device applications and the BlackBerry Java Application. The memory capabilities represent the total amount of available memory, which is larger than the available working memory when all of the applications and associated application data exist on the BlackBerry device.

BlackBerry device memory

BlackBerry devices include the following types of memory: Memory flash Description The BlackBerry operating system and all application modules are stored persistently in flash memory. When a BlackBerry device user turns on the BlackBerry device, the core operating system and the BlackBerry Java Application modules use approximately 10 MB to 15 MB of flash memory, depending on the version. Flash memory can store the BlackBerry device user's email messages, organizer data, and other personal information, as well as the data that a BlackBerry Java Application stores in memory. SRAM controls the transient data objects and runtime processes. The microSD card stores media files, documents, and persistent data from a BlackBerry Java Application.
SRAM microSD expandible memory card

Key resources to reserve

Flash memory: The persistent storage space that is available on the BlackBerry device is a fixed amount of flash memory, typically in the range of 8 MB to 64 MB. Persistent object handles: The handles that are assigned to each persistent object are consumed only by persistent objects. The amount of flash memory on the BlackBerry device determines the fixed number of persistent object handles in the system. Object handles: Each object and array of primitives has an object handle associated with it. The amount of flash memory on the BlackBerry device determines the fixed number of object handles in the system.
Managing low memory availability
Best practice: Minimizing memory use
To minimize runtime memory, consider the following guidelines: Use primitive types (such as int or Boolean) instead of objects (such as String or Integer). Do not depend entirely on the garbage collector. Avoid creating many objects quickly. Set object references to null when you are finished using them. Reuse objects as much as possible. Move heavy processing to the server. For example, you can filter or sort data before sending it to the BlackBerry device.

The low memory manager handles memory resources on the BlackBerry device when the available memory resources fall below a certain threshold. The low memory manager attempts to free used memory to provide more available memory on the BlackBerry device. All applications, including BlackBerry Java Applications, should work with the low memory manager to free as much memory as possible when the BlackBerry device is low on memory resources.
Identifying low memory availability on a BlackBerry device
The following conditions can cause the low memory manager to attempt to free memory resources: The amount of available flash memory on the BlackBerry device falls below a certain threshold. The flash memory threshold depends on the amount of free RAM in the system. The flash memory threshold ranges between 400 KB and 800 KB. The number of persistent object handles that are available on the BlackBerry device falls below 1000 persistent object handles. The number of object handles that are available on the BlackBerry device falls below 1000 object handles.

Conserving resources

Best practice: Using efficient data structure selection
Data structure selection defines how many object handles and how much flash memory a BlackBerry Java Application consumes. Improper data structure selection can consume key resources without improving the BlackBerry Java Application functionality or the BlackBerry device user experience. Consider the following guidelines:
The data structure should consist of the minimum possible number of objects, especially when you use high-level objects like a Vector or a Hashtable. These classes provide significant functionality but are not efficient storage mechanisms and you should avoid using them in the persistent store if possible. When possible, use primitives instead of objects, because primitives reduce the number of object handles that are consumed on the BlackBerry device. An array of primitives is an object and consumes an object handle. String objects are as efficient as byte arrays. A String object consumes only one object handle and is equivalent if your application stores all of the characters as a byte. In other words, the value of each character is less than or equal to the decimal value of 255. If your application cannot store characters as a byte, you can store the characters as a String because it is equivalent to storing a char array.
Best practice: Consolidating objects into object groups
One of the most common errors that application developers encounter is an exhaustion of persistent object handles. The amount of flash memory on the BlackBerry device determines the fixed number of persistent object handles that are available in the system. Depending on the data structure selection, stored records can quickly exhaust the number of persistent object handles. A persistent object consumes a persistent object handle and an object handle. A transient object consumes only an object handle. For example, a record that contains ten String fields, which represent items like a name, a phone number, and an address, consumes 11 persistent object handles, one for the record object and one for each String. If a BlackBerry Java Application persists 3000 records, the application consumes 33,000 persistent object handles, which exceeds the number of persistent object handles available on a BlackBerry device with 16 MB of flash memory. You can use the net.rim.device.api.system.ObjectGroup class to consolidate the object handles for an object into one group. Using the example in the previous paragraph, if you group the record, the record consumes one persistent object handle instead of 11. The object handles for the String fields consolidate under the record object handle. When you consolidate object handles into one group, the object handle is read-only. You must ungroup the object before you can change it. After you complete the changes, group the object again. If you attempt to change a grouped object without first ungrouping it, an ObjectGroupReadOnlyException is thrown. Ungrouping an object has a performance impact. The system creates a copy of the grouped object and allocates handles to each of the objects inside that group. Therefore, objects should only be ungrouped when necessary.

Security considerations

Data encryption and the BlackBerry Application
Data encryption in transport
If you use the BlackBerry Enterprise Server as the network gateway for your application, the BlackBerry Enterprise Server encrypts data using AES or TripleDES encryption at all points in the connection between the BlackBerry device and the BlackBerry Enterprise Server behind the organization's firewall. If you require data to be encrypted further between the BlackBerry Enterprise Server and the destination server, you can use the HTTPS protocol and use SSL/TLS encryption. If your application uses the BlackBerry Internet Service or the Internet gateway of the wireless service provider, data traffic is not encrypted. If your BlackBerry device users prefer, you can use HTTPS to encrypt the data, or you can use the Java APIs for encryption to apply your own symmetric key or public key cryptography.
Data encryption on the BlackBerry device
Administrators can set an IT policy to make sure that all BlackBerry device user data stored in the BlackBerry device applications is encrypted locally in flash memory. You can create aBlackBerry Java Application that uses APIs to register the data so that the encryption service encrypts the data with the same security key before storing it in flash memory.

Access to memory

The BlackBerry Java Development Environment is designed to inhibit applications from causing problems accidentally or maliciously in other applications or on the BlackBerry device. BlackBerry applications can write only to the BlackBerry device memory that the BlackBerry Java Virtual Machine uses; they cannot access the virtual memory or the persistent storage of other applications (unless they are specifically granted access to do so). A BlackBerry Java Application can only access persistent storage or user data, or communicate with other applications, through specific BlackBerry APIs. Research In Motion must digitally sign a BlackBerry Java Application that uses these BlackBerry APIs, to provide an audit trail of applications that use sensitive APIs.

Authentication

BlackBerry device authentication and IT policy
BlackBerry device users can set a password for their BlackBerry devices. When the device password is active, the BlackBerry device users must provide the password to access the data and applications. Using device passwords is a good first step to limiting access to your BlackBerry Java Application on the BlackBerry device. Administrators can use the IT policies that are provided in the BlackBerry Enterprise Server to make sure that BlackBerry devices in the organization are password-protected. Administrators can also use IT policies to remotely lock a BlackBerry device, change the password, or remove all of the data.

You can run applications that use controlled APIs in the BlackBerry Smartphone Simulator without code signatures; however, you must obtain code signatures from Research In Motion before you can install these applications on BlackBerry devices. You can use the following categories of RIM controlled APIs: Runtime APIs BlackBerry Application APIs BlackBerry Cryptographic API If you use any of the following BlackBerry API packages, your application requires code signatures before you can install it on a BlackBerry device: net.rim.blackberry.api.browser net.rim.blackberry.api.invoke net.rim.blackberry.api.mail net.rim.blackberry.api.mail.event net.rim.blackberry.api.menuitem net.rim.blackberry.api.options net.rim.blackberry.api.pdap net.rim.blackberry.api.phone net.rim.blackberry.api.phone.phonelogs net.rim.device.api.browser.field net.rim.device.api.browser.plugin net.rim.device.api.crypto.* net.rim.device.api.io.http net.rim.device.api.notification net.rim.device.api.servicebook net.rim.device.api.synchronization net.rim.device.api.system
For more information about RIM controlled APIs, see the BlackBerry API reference.

IT policy support

You can use the APIs in the net.rim.device.api.itpolicy package to access the IT policy information on the BlackBerry device and change the behavior or functionality of a BlackBerry device application. Each IT policy item consists of a name, a description, and a value. The value can be a string, integer, or Boolean value. BlackBerry device IT policy settings are automatically synchronized and updated over the wireless network with BlackBerry Device Software version 3.6 or later. With earlier versions of the BlackBerry Device Software, IT policy settings are updated when the BlackBerry device user synchronizes the BlackBerry device with the computer. For more information about IT policies, see the BlackBerry Enterprise Server Policy Reference Guide.

Application control

The BlackBerry Enterprise Server application control policy rules are designed to allow or prevent the installation of specific applications on the BlackBerry device and to limit the permissions of applications on the BlackBerry device. For example, administrators can use the application control policy to make sure that a game application on the BlackBerry device cannot access the phone application. The administrator can apply application control policies only when the BlackBerry device is associated with a BlackBerry Enterprise Server. If the administrator or a BlackBerry device user denies the application access to one of the protected areas, the application throws a ControlledAccessException.

Preverifying a BlackBerry Java Application
When you preverify your classes, you reduce the amount of processing that the BlackBerry device must perform when you install your application. To partially verify your classes before you install your application on a BlackBerry device, you can use the Preverify tool, available with the BlackBerry Java Development Environment. You can use the BlackBerry Smartphone Simulator to preverify the.cod files. For more information about using the BlackBerry Smartphone Simulator, see the BlackBerry Device Simulator User Guide. For more information about using the Preverify tool, see the BlackBerry Java Development Environment Development Guide.
Testing applications on a BlackBerry Smartphone Simulator
After you develop and compile your application, you can test it on the BlackBerry device. The most common first step is to set the BlackBerry Java Development Environment to use a BlackBerry Smartphone Simulator. The BlackBerry Smartphone Simulator runs the same Java code as the BlackBerry devices, so the BlackBerry Smartphone Simulator provides an accurate environment for testing how applications will function on a BlackBerry device. The BlackBerry JDE includes current versions of the BlackBerry Smartphone Simulator. To download additional versions of the BlackBerry Smartphone Simulator, visit www.blackberry.com/developers/index.shtml.
Testing applications on a BlackBerry device
After you test your application on the BlackBerry Smartphone Simulator, you can install your application on a BlackBerry device. If your application uses signed APIs, you might need code signing keys. After you install the application on the BlackBerry device, you can open the application and test its functionality and performance. For debugging purposes, you can attach your device to the BlackBerry Integrated Development Environment and use the debugging tool to step through your application code. The BlackBerry IDE can be useful if you are trying to identify a network or Bluetooth issue, or other issues that are difficult to simulate.

BlackBerry simulators

BlackBerry Smartphone Simulator
The BlackBerry Smartphone Simulator is designed to emulate a BlackBerry experience without using a real BlackBerry device. The BlackBerry Smartphone Simulator is an application that you install on your computer that shows an image of the BlackBerry device model of your choice. This image has the look and feel of an actual BlackBerry device. The functionality includes the same user interaction of an actual BlackBerry device (including the trackwheel or trackball and the keyboard), the same applications, and the same features, such as email messages, phone, and Internet browsing. The BlackBerry Smartphone Simulator also serves as a platform on which applications can run. This includes the ability for the applications to make network connections, store data, and handle email messages. The BlackBerry Smartphone Simulator includes the BlackBerry device applications that are typically available on BlackBerry devices and you can install and test your own applications. You can simulate and test various connectivity and state changes using the BlackBerry Smartphone Simulator. When you use the BlackBerry Smartphone Simulator to perform testing, you might need to simulate additional BlackBerry services. The BlackBerry MDS Simulator and the BlackBerry Email Simulator are available for this purpose. To get the BlackBerry Smartphone Simulator, visit www.blackberry.com/developers and download the BlackBerry Java Development Environment or the BlackBerry Java Development Environment Component Package.

BlackBerry MDS Simulator

The BlackBerry MDS Simulator is designed to simulate the BlackBerry MDS Connection Service component of the BlackBerry Enterprise Server. When you use the BlackBerry Smartphone Simulator with the BlackBerry MDS Simulator you can test network, push HTTP, and browser applications that are designed for use with a BlackBerry Enterprise Server. To get the BlackBerry MDS Simulator, visit www.blackberry.com/developers and download the BlackBerry Email and MDS Services Simulator Package.
BlackBerry Email Simulator
The BlackBerry Email Simulator is designed to send and receive messages between the BlackBerry Smartphone Simulator and either a messaging application, such as Microsoft Outlook, or POP3 and SMTP servers. You do not require a BlackBerry Enterprise Server. To get the BlackBerry Email Simulator, visit www.blackberry.com/developers and download the BlackBerry Email and MDS Services Simulator Package.