BlackBerry Java ApplicationCoreVersion: 5.0Development Guide

Published: 2010-12-10SWD-790641-1210113811-001

Contents1 Managing applications.Application manager.Retrieve information about a BlackBerry Java Application.Communicate with another BlackBerry Java Application.Determine the services that are available to a BlackBerry Java Application.Application control.Request access to resources.Code modules.Retrieve module information.Access control messages.Displaying a message for an operation that requires user permission.Display an application control message to a user.5555666777772 Storing data.Data management.Access to memory.File systems and paths.File Connections APIs.Storage on removable media.Accessing data on the microSD media card.Using the microSD media card with more than one BlackBerry device.File encryption on microSD cards.IT policies and the microSD media card.Encryption of data on a microSD media card.Code sample: Reading sections of a binary file.Persistent data storage.Create a persistent data store.Store persistent data.Retrieve persistent data.Remove persistent data.MIDP record storage.Create an MIDP record store.Add a record to a record store.Retrieve a record from a record store.Retrieve all records from a record store.Collections.Retrieve a collection from persistent 5

Create a collection listener to notify the system when a collection changes.Remove a collection listener that notifies the system when a collection changes.Notify the system when a collection changes.Runtime storage.Retrieve the runtime store.Add an object in the runtime store.Replace an object in the runtime store.Retrieve a registered runtime object.Retrieve an unregistered runtime object.1617171818181819193 Creating connections.Network connections and transport types.Using the BlackBerry Enterprise Server as an intranet gateway.Using the wireless service provider's Internet gateway.Retrieve the wireless network name.Connections.Use HTTP authentication.Use an HTTPS connection.Use a socket connection.Use a datagram connection.Use a USB or serial port connection.Use a Bluetooth serial port connection.Wi-Fi connections.Wireless access families.Retrieve the wireless access families that a BlackBerry device supports.Determine if a BlackBerry device supports multiple wireless access families.Determine the wireless access family transceivers that are turned on.Turn on the transceiver for a wireless access family.Turn off the transceiver for a wireless access family.Check if the Wi-Fi transceiver is turned on.Check if the Wi-Fi transceiver is connected to a wireless access point.Retrieve the status of the wireless access point or the active Wi-Fi profile.Retrieve the wireless network name.Open a Wi-Fi socket connection.Open a Wi-Fi HTTP connection.Open a Wi-Fi HTTPS connection.Enhanced Network API.Code sample: Displaying available transport types.Code sample: Creating a connection over HTTP by using the first available 293030303131313233

4 Controlling access to APIs and application data.Check if a code signature is required.Java APIs with controlled access.Register to use controlled APIs.Restrictions on code signatures.Request a code signature.Register a signature key using a proxy server.Sign an application using a proxy server.View the signature status for an application.Using keys to protect APIs and data.Protect APIs using code signing keys.Protect runtime store data using code signing keys.Protect persistent data using code signing keys.353535363637373838383839405 Testing a BlackBerry device application.Testing applications on a BlackBerry Smartphone Simulator.Testing applications on a BlackBerry device.Testing applications using the compiled .cod files.Install and remove a .cod file for testing.Save a .cod file from a device to a computer.Retrieve information about a .cod file.414141414242426 Packaging and distributing a BlackBerry Java Application.Preverify a BlackBerry device application.Application distribution over the wireless network.Wireless pull (user-initiated).Wireless push (server-initiated).Distributing BlackBerry Java Applications over the wireless network.Extract sibling .cod files.Modifying information for a MIDlet suite.Properties of BlackBerry device application .jad files.Correct the .cod file sizes listed in a .jad file.Create .jad files that reference multiple .cod files.Distributing BlackBerry device applications with the BlackBerry Desktop Software.Elements in BlackBerry device application .alx file.Application distribution through a computer connection.Distribute an application from a computer.Distribute an application from a web page.44444444444545454647474747525252

Distribute an application for testing.Distributing an application from a computer.Create an application loader file.Install a BlackBerry device application on a specific device.Specifying supported versions of the BlackBerry Device Software.Specifying a location for your application on a BlackBerry device.Specify a location for your application on a BlackBerry device.525353535455567 Localizing BlackBerry device applications.Multilanguage support.Files required for localization.Manage localization files for a suite of BlackBerry device applications.575757588 Custom user authentication.599 Glossary.6010 Provide feedback.6311 Related resources.6412 Document revision history.6513 Legal notice.66

Development GuideManaging applicationsManaging applications1Application managerThe BlackBerry Java Virtual Machine on the BlackBerry device includes an application manager that is the centraldispatcher of operating system events for other BlackBerry device applications.The net.rim.device.api.system.ApplicationManager class lets applications interact with the applicationmanager to perform the following actions: interact with processes, such as retrieving the IDs for foreground applicationspost global events to the systemrun an application immediately or at a specific timeRetrieve information about a BlackBerry Java Application1.Import the required classes and .rim.device.api.system.*;To retrieve information about the processes that are running, ApplicationManager manager tionDescriptor descriptors[] manager.getVisibleApplications();3.To retrieve descriptions of the objects for the BlackBerry device applications that are running, invokeApplicationDescriptor.getName().String appname1 descriptors[0].getName();4.To retrieve a description of the current application, riptor().ApplicationDescriptor descriptor ();Communicate with another BlackBerry Java Application1.2.Import the net.rim.device.api.system.ApplicationManager class.To post a system-level event to another BlackBerry device application, invoke one of theApplicationManager.postGlobalEvent() methods.5

Development GuideApplication controlDetermine the services that are available to a BlackBerry Java ApplicationThe service book consists of service records. Each service record defines a service on a BlackBerry device. Servicerecords define the communication protocol (WAP or IPPP), the network gateway, and the configuration informationsuch as the browser settings.1.2.Import the net.rim.device.api.servicebook class.To let your BlackBerry device application interact with the BlackBerry Infrastructure, use the service book API(net.rim.device.api.servicebook).Application controlThe BlackBerry Application Control IT policy rules provide administrators with the ability to establish the capabilitiesof an application when it runs on a specific BlackBerry device. For example, administrators can use the BlackBerryApplication Control IT policy rule to make sure that a game that exists on the BlackBerry device cannot access thephone API. The BlackBerry Application Control IT policy rule works only when the BlackBerry device is connected toa BlackBerry Enterprise Server. This IT policy does not apply to BlackBerry devices that use the BlackBerry InternetService only.If the administrator or a user denies the application access to one of the protected areas, the associated methodthrows a ControlledAccessException. For class-level checks, the method throws a NoClassDefFoundError.Depending on which APIs that you use, your application might need to handle both types of errors.Request access to resources1.Import the required classes and interfaces.import ermissions;import ermissionsManager;2.Create an instance of the ApplicationPermissions class.ApplicationPermissions permissions new ApplicationPermissions();3.Specify the build request to ask for event injection privileges.permissions.addPermission( ApplicationPermissions.PERMISSION EVENT INJECTOR );4.Determine the access control settings that the BlackBerry device user em.out.println("The user allowed requested permissions.");}else{System.out.println("The user denied requested permissions.");}6

Development GuideCode modulesCode modulesRetrieve module information1.2.Import the net.rim.device.api.system.CodeModuleManager class.To retrieve a handle for a module, invoke getModuleHandle(), and provide the name of the code module asa handle CodeModuleManager.getModuleHandle("test module");3.To retrieve specific information about a module, invoke the methods of the CodeModuleManager class, andprovide the module handle as a parameter to these methods.String name CodeModuleManager.getModuleName( handle );String vendor CodeModuleManager.getModuleVendor( handle );String description CodeModuleManager.getModuleDescription( handle );int version CodeModuleManager.getModuleVersion( handle );int size CodeModuleManager.getModuleCodeSize( handle );int timestamp CodeModuleManager.getModuleTimestamp( handle );4.To retrieve an array of handles for existing modules on a BlackBerry device, invoke getModuleHandles().int handles[] CodeModuleManager.getModuleHandles();String name CodeModuleManager.getModuleName( handles[0]);Access control messagesDisplaying a message for an operation that requires user permissionYou can use the components of the net.rim.device.api.applicationcontrol package to let a BlackBerry device application display custom messages to a BlackBerry device user when the application attempts an operationthat the user must permit. The application displays information about the type of permission that the user mustprovide. For example, you can use PERMISSION PHONE for an operation that requires access to the phonefunctionality of the device.You can use the applicationcontrol package to include a custom message with the default message that anapplication displays in response to an application control.Display an application control message to a userA BlackBerry device application can include more than one registered ReasonProvider.The application displaysmessages from ReasonProviders in the order that each ReasonProvider registers with the application. Forexample, if an application registers a ReasonProvider A before ReasonProvider B, the application displays themessage from ReasonProvider A, followed by the message from ReasonProvider B.1.Import the net.rim.device.api. applicationcontrol.ReasonProvider interface.7

Development Guide2.8Access control messagesIn your implementation of the ReasonProvider.getMessage(int permissionID) method, return aString value that contains the message to display to the user.

Storing dataDevelopment GuideStoring data2Data managementYou can store data to persistent memory on the BlackBerry device. The BlackBerry Persistent Store APIs and theMIDP RMS APIs provide support for JSR 37 and JSR 118. A BlackBerry device that runs BlackBerry Device Softwareversion 4.2 or later also provides a traditional file system and support for saving content directly to the file systemusing JSR 75 APIs. With either the BlackBerry Persistent Store APIs or the MIDP RMS APIs, you can store datapersistently to flash memory. The data persists even if you remove the battery from the BlackBerry device.A BlackBerry device that runs BlackBerry Device Software version 5.0 or later also supports the use of SQLite . Youmust use the JSR 75 APIs or SQLite to store data on a media card.Access to memoryThe BlackBerry Java environment is designed to inhibit applications from causing problems accidentally ormaliciously in other applications or on the BlackBerry device. BlackBerry device applications can write only to theBlackBerry device memory that the BlackBerry Java Virtual Machine uses; they cannot access the virtual memory orthe persistent storage of other applications (unless they are specifically granted access to do so). Custom applicationscan only access persistent storage or user data, or communicate with other applications, through specific APIs.Research In Motion must digitally sign applications that use certain BlackBerry APIs, to provide an audit trail ofapplications that use sensitive APIs.File systems and pathsThe file systems on a BlackBerry device have corresponding file paths that you use to access them.File system mounting pointinternal flashmedia cardPathfile:///store/.file:///SDCard.File Connections APIsThe File Connection APIs provide a traditional file system, and support for saving data directly to the file system onthe BlackBerry device or to a microSD card. You can view data in the file system and move the data to a computerby using Windows .9

Storage on removable mediaDevelopment GuideStorage on removable mediaAccessing data on the microSD media cardThe package supports the JSR 75 File Connection APIs and is used in applicationsto access the file system for the microSD media card. You can also implement the FileConnection interface toaccess BlackBerry device ring tones and camera images.Class or tionDescriptionThis exception is thrown when an application invokes a method on a closedfile connection.An application can use this API to access files or directories.An application can use this API to receive status notifications when theapplication adds or removes a file system root.An application can use this API as a central registry for file system listenersthat listen for the addition or removal of file systems.This exception is thrown when a method requires a specific security mode(for example READ or WRITE) and the open connection is not in that mode.Using the microSD media card with more than one BlackBerry deviceIf the BlackBerry device user moves the microSD media card to a BlackBerry device that does not use a devicepassword or uses a password that does not successfully decrypt the microSD media card master key, the BlackBerrydevice prompts the BlackBerry device user to enter the microSD media card password. If the BlackBerry device hasa password, the BlackBerry device user can use the prompt to change the microSD media card password to theBlackBerry device password.File encryption on microSD cardsIT policies and the microSD media cardYou can apply the IT policy Encrypt data written to the microSD media card to any new or modified files that youstore on the microSD media card. Only the files that you store on the microSD media card after an administrator setsthe IT policy are encrypted. Except for media files, all content is encrypted.Encryption of data on a microSD media cardWhen a BlackBerry Java Application accesses a file on the microSD memory card, file decryption occurs and thefile moves to main memory for an application to read. For a BlackBerry Java Application to access a file that is passwordprotected, the BlackBerry device must not be locked. Encrypted files have a .rem extension and cannot be decryptedon platforms other than BlackBerry.10

Development GuideCode sample: Reading sections of a binary fileIf the NVRAM is removed and the microSD media card is locked with a BlackBerry device key, the data on the microSDmedia card is no longer accessible. To remove data that is not accessible, start the BlackBerry device and remove allencrypted media files.The BlackBerry device uses a master key stored on the microSD media card to encrypt BlackBerry device media files.The master key prevents the BlackBerry device from having to decrypt or re-encrypt all media files when you disableencryption or change the password.Code sample: Reading sections of a binary fileThis code sam

Determine the services that are available to a BlackBerry Java Application The service book consists of service records. Each service record defines a service on a BlackBerry device. Service records define the communication protocol (WAP or IPPP), the network gateway, and the c