BlackBerry Java

Development Environment
Version 4.0.2

BlackBerry Application Developer Guide

Volume 2: Advanced Topics

BlackBerry Java Development Environment Version 4.0.2 BlackBerry Application Developer Guide Volume 2: Advanced Topics

Last modified: 14 June 2005

Part number: SWD_X_JDE(EN)-002.001

At the time of publication, this documentation complies with BlackBerry JDE Version 4.0.2.

© 2005 Research In Motion Limited. All rights reserved. The BlackBerry and RIM families of related marks, images and symbols are the exclusive
properties of Research In Motion Limited. RIM, Research In Motion, BlackBerry and 'Always On, Always Connected' are registered with the U.S.
Patent and Trademark Office and may be pending or registered in other countries.

Microsoft, Windows, and Outlook are registered trademarks of Microsoft Corporation in the United States and/or other countries. Java is a trademark
of Sun Microsystems, Inc. in the U.S. and other countries. IBM, Lotus, and Domino are trademarks of International Business Machines Corporation in
the United States, other countries or both. All other brands, product names, company names, trademarks, and service marks are the properties of
their respective owners.

The handheld and/or associated software are protected by copyright, international treaties and various patents, including one or more of the
following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D,445,428; D,433,460; D,416,256. Other patents are registered
or pending in various countries around the world. Please visit www.rim.net/patents.shtml for a current listing of applicable patents.

This document is provided “as is” and Research In Motion Limited (RIM) assumes no responsibility for any typographical, technical, or other
inaccuracies in this document. RIM reserves the right to periodically change information that is contained in this document; however, RIM makes no
commitment to provide any such changes, updates, enhancements, or other additions to this document to you in a timely manner or at all. RIM
MAKES NO REPRESENTATIONS, WARRANTIES, CONDITIONS, OR COVENANTS, EITHER EXPRESS OR IMPLIED (INCLUDING, WITHOUT LIMITATION,
ANY EXPRESS OR IMPLIED WARRANTIES OR CONDITIONS OF FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, MERCHANTABILITY,
DURABILITY, TITLE, OR RELATED TO THE PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE REFERENCED HEREIN, OR PERFORMANCE
OF ANY SERVICES REFERENCED HEREIN). IN CONNECTION WITH YOUR USE OF THIS DOCUMENTATION, NEITHER RIM NOR ITS AFFILIATED
COMPANIES AND THEIR RESPECTIVE DIRECTORS, OFFICERS, EMPLOYEES, OR CONSULTANTS SHALL BE LIABLE TO YOU FOR ANY DAMAGES
WHATSOEVER BE THEY DIRECT, ECONOMIC, COMMERCIAL, SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY, OR INDIRECT DAMAGES,
EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, INCLUDING, WITHOUT LIMITATION, LOSS OF BUSINESS REVENUE OR
EARNINGS, LOST DATA, DAMAGES CAUSED BY DELAYS, LOST PROFITS, OR A FAILURE TO REALIZE EXPECTED SAVINGS.

This document might contain references to third-party sources of information and/or third-party web sites (“Third-Party Information”). RIM does not
control, and is not responsible for, any Third-Party Information, including, without limitation, the content, accuracy, copyright compliance, legality,
decency, links, or any other aspect of Third-Party Information. The inclusion of Third-Party Information in this document does not imply endorsement
by RIM of the third party in any way. Any dealings with third parties, including, without limitation, compliance with applicable licenses, and terms
and conditions are solely between you and the third party. RIM shall not be responsible or liable for any part of such dealings.

Research In Motion Limited Research In Motion UK Limited

295 Phillip Street Centrum House, 36 Station Road
Waterloo, ON N2L 3W8 Egham, Surrey TW20 9LF
Canada United Kingdom

Published in Canada
Contents
Using controlled APIs .................................................................................................................................... 5
BlackBerry controlled APIs.............................................................................................................................................5
Code signatures.................................................................................................................................................................6

Integrating messages ..................................................................................................................................11

Mail API............................................................................................................................................................................. 11
Working with messages ............................................................................................................................................... 13
Managing folders........................................................................................................................................................... 18
Managing attachments................................................................................................................................................ 19

Integrating PIM functions ..........................................................................................................................23

PIM APIs............................................................................................................................................................................ 23
Using the address book ............................................................................................................................................... 25
Using tasks....................................................................................................................................................................... 31
Using the calendar ........................................................................................................................................................ 37

Adding handheld options ...........................................................................................................................43

Options API...................................................................................................................................................................... 43
Adding option items ..................................................................................................................................................... 43

BlackBerry Browser ......................................................................................................................................47

Browser APIs.................................................................................................................................................................... 47
Displaying web content in the browser.................................................................................................................. 47
Displaying web content in a browser field............................................................................................................ 48
Supporting additional MIME types.......................................................................................................................... 62
Registering as an HTTP filter ..................................................................................................................................... 67

Accessing the phone application ..............................................................................................................73

Phone API......................................................................................................................................................................... 73
Listening for phone events ......................................................................................................................................... 74
Accessing and managing phone logs ..................................................................................................................... 75

Communicating with BlackBerry applications.......................................................................................79

Starting BlackBerry applications ............................................................................................................................... 79
Adding menu items to BlackBerry applications................................................................................................... 80

Storing persistent data ...............................................................................................................................83

Persistent storage options........................................................................................................................................... 83
Managing persistent data........................................................................................................................................... 85
Memory management and persistent objects...................................................................................................... 89
Managing custom objects........................................................................................................................................... 90

Backing up and restoring persistent data ..............................................................................................97

Synchronization API ...................................................................................................................................................... 97
 Adding support for backing up persistent data................................................................................................... 98

Accessing setup and configuration information ................................................................................ 107

Service book API.......................................................................................................................................................... 107

Managing notifications............................................................................................................................ 109

Notification API........................................................................................................................................................... 109
Adding events .............................................................................................................................................................. 109
Responding to events................................................................................................................................................ 115
Customizing system notifications.......................................................................................................................... 116

Managing applications ............................................................................................................................ 123

Application manager ................................................................................................................................................. 123
Managing code modules.......................................................................................................................................... 125

Sharing runtime objects between applications .................................................................................. 129

Sharing runtime objects............................................................................................................................................ 129

Glossary ....................................................................................................................................................... 131

Index............................................................................................................................................................. 133
 1
Using controlled APIs
• BlackBerry controlled APIs
• Code signatures

BlackBerry controlled APIs

The BlackBerry® APIs described in this guide have controlled access. Applications that use controlled
APIs can be run in the simulator; however, you must obtain code signatures from Research In Motion®
(RIM®) before you can load these applications onto BlackBerry devices. See “Code signatures” on page 6
for more information.

Package Description
net.rim.blackberry.api.browser This package enables applications to invoke the BlackBerry Browser. See
“Displaying web content in the browser” on page 47 for more information.
net.rim.blackberry.api.invoke This package enables applications to invoke BlackBerry applications, such as
tasks, messages, MemoPad, and phone. See “Starting BlackBerry applications”
on page 79 for more information.
net.rim.blackberry.api.mail This package enables applications to interact with the BlackBerry messages
application to send, receive, and open messages. See “Working with messages”
on page 13 for more information.
net.rim.blackberry.api.mail.event This package defines messaging events and listener interfaces to manage mail
events. See “Mail events” on page 13 for more information.
net.rim.blackberry.api.menuitem This package enables you to add custom menu items to BlackBerry applications,
such as the address book, calendar, and messages. See “Adding menu items to
BlackBerry applications” on page 80 for more information.
net.rim.blackberry.api.options This package enables you to add items to the handheld options. See “Adding
option items” on page 43 for more information
net.rim.blackberry.api.pdap This package enables applications to interact with BlackBerry personal
information management (PIM) applications, including address book, tasks,
and calendar. Most of the same functionality is provided by the MIDP package
javax.microedition.pim. See “PIM APIs” on page 23 for more information.
net.rim.blackberry.api.phone This package provides access to advanced features of the phone application.
See “Phone API” on page 73 for more information.
net.rim.blackberry.api.phone.phonelogs This package provides access to the phone call history. See “Accessing and
managing phone logs” on page 75 for more information.
net.rim.device.api.browser.field This package enables applications to display a browser field within their user
interface. See “Displaying web content in a browser field” on page 48 for more
information.
net.rim.device.api.browser.plugin This package enables you to add support for additional MIME types to the
BlackBerry Browser. See “Supporting additional MIME types” on page 62 for
more information.
net.rim.device.api.crypto.* These packages provide data security capabilities, including data encryption
and decryption, digital signatures, data authentication, and certificate
management. See the API Reference for more information.
net.rim.device.api.io.http This package enables applications to register with the BlackBerry Browser as
provider for one or more URLs. See “Registering as an HTTP filter” on page 67
for more information.
BlackBerry Application Developer Guide

Package Description
net.rim.device.api.notification This package provides methods to trigger event notifications and respond to
system-wide and application-specific events. See “Notification API” on page
109 for more information.
net.rim.device.api.servicebook This package enables applications to add, delete, and access service book
entries. See “Accessing setup and configuration information” on page 107 for
more information.
net.rim.device.api.synchronization This package enables applications to perform backup and restore operations on
custom data. See “Adding support for backing up persistent data” on page 98
for more information.
net.rim.device.api.system This package provides classes that enable functionality such as persistent data
storage, interprocess communication (IPC), SMS, network communication using
datagrams, and application management.
• See “Application manager” on page 123 for more information.
• See “Using datagram connections” on page 98 for more information.
• See “Storing persistent data” on page 83 for more information.

Code signatures
RIM tracks the use of some sensitive APIs in the BlackBerry JDE for security and export reasons. In the
API Reference, a lock icon or the text signed indicates sensitive classes or methods. In the
documentation for a class that contains signed methods, select or clear the SHOW Signed option at the
top of the page to view or hide signed methods.
If you use signed classes or methods in your applications, the .cod files must be digitally signed by RIM
before you can load them onto BlackBerry devices.
Note: To test and debug your code before receiving code signatures, use the simulator. Code must be signed only for
deployment to BlackBerry devices.

Use the Signature Tool, which is installed with the BlackBerry JDE, to request the appropriate signatures
for your .cod files.
Note: You never send your actual code to RIM. The Signature Tool sends an SHA-1 hash of your code file so that the signing
authority system can generate the necessary signature.

Code signature verification

Code signature verification types Description
Linktime verification When you load a signed .cod file onto the BlackBerry device, the virtual machine (VM) links
the .cod file with the API libraries and verifies that the .cod file includes the required
signatures. If a signature is missing, the VM stops linking and does not load the application.
Runtime verification When the user uses the application on the BlackBerry device, if the application invokes a
method that requires a signature, the VM verifies that the application contains the
necessary signature. If the signature is not present, a ControlledAccessException is
thrown, and the requested operation is not performed.

See “Registering for code signing” on page 8 for more information on .csi files. See “Requesting code
signatures” on page 9 for more information on .csl and .cso files.

6
 1: Using controlled APIs

Code signing request process

1. The Signature Tool opens an HTTP connection to the signing authority system and sends a request.
The request includes a hash of your code in the .csl and .cso files. Your actual code is not sent to
RIM.
2. The signing authority system verifies that the request is valid and applies a RIM private key to the
hash of each .cod file to create the signatures.
3. The signing authority system returns the signatures to the Signature Tool and closes the HTTP
connection.
4. The Signature Tool appends the signatures to each .cod file.
When the files are signed, the Status column for the .cod file displays Signed.
If any problems occur with the signature request, the Status column displays Failed - See Details.
When your .cod files are signed, you can load them onto the BlackBerry device. See the BlackBerry
Application Developer Guide Volume 1 – Fundamentals for more information.

Optional signatures
You can load applications onto BlackBerry devices without optional .cso signatures. These signatures are
only required if their corresponding methods are invoked during runtime.
When the application calls a method that requires a signature, the VM verifies that the application has
this authorization. If the VM does not find these optional signatures, the application stops.

Signing limitations
There are several situations in which the code signing process does not proceed.

Client parameters
The signing authority administrator can limit your access to signatures by specifying a limit using both
time and frequency parameters. These parameters are defined in your .csi file. Be aware of these possible
limitations when applying for signatures.

Parameter Definition
# of Requests This parameter sets the number of requests you can make using a particular .csi file. After you make
the maximum number of requests, the .csi file is invalid and you can no longer make signature requests
using this file. Contact your signing authority administrator to apply for another .csi file.
Requests are limited for security reasons; however, the signing authority administrator can allow you
to make an infinite number.
Expiry Date This parameter sets the expiry date for your .csi file. After your .csi file expires, you can no longer make
signature requests using this file. Contact your signing authority administrator and apply for another
.csi file.

To request a change in these .csi parameters, contact your signing authority administrator.

Lost data
You cannot perform any code signing requests without your .csi file. Your registration key is stored within
your .csi file. None of your signature requests can be sent to the signing authority system if the Signature
Tool cannot find this key and sign your requests with it.

7
BlackBerry Application Developer Guide

If your system stops responding, and you lose data or even entire file structures, you might discover that
you have also lost the ability to perform signing requests. If you lose your .csi file, the Signature Tool
cannot communicate with the signing authority system on your behalf.
If you lose your .csi file, contact your signing authority administrator and request a new one.

Registering for code signing

You require a separate set of code signing keys for each computer that requests keys. Once keys are
installed on a computer, they cannot be reinstalled or moved to another computer.

Register for code signatures

You must have HTTP access to the Internet to register for code signing.
1. To activate your account, complete the registration form on the BlackBerry Developer Zone at
http://www.blackberry.com/developers.
In this form, you provide a ten-digit personal information number (PIN).
2. When you receive .csi files in an email message from RIM, save them to your computer.
3. Double-click a .csi file.
If a dialog box appears that states that a private key cannot be found, perform the following actions
before you continue:
• Click Yes to create a new key pair file.
• Type a password for your private key, and retype to confirm.
• Click OK.
• Move your mouse to generate data for a new private key.
4. In the Registration PIN field, type the PIN that was provided on the Signature Request form or that
RIM provided.
5. In the Private Key Password field, type a password of at least eight characters. This is your private
key password, which protects your private key.
Note: Protect your private key password. If you lose this password, you must register with RIM again. If this password is
stolen, contact RIM immediately to revoke your key to prevent others from requesting code signatures using your identity.

6. Click Register.
7. Click Exit.

Changing your private key password

You must have HTTP access to the Internet to change your private key password.

Change your private key password

1. In the BlackBerry JDE bin folder, double-click SignatureTool.jar.
2. Click Change Password.
3. In the Old Password field, type your current private key password.
4. Click Verify.
5. Type and confirm a new password.

8
 1: Using controlled APIs

6. Click OK.

Requesting code signatures

Request a code signature from the IDE
1. Build your projects.
In the IDE, on the Build menu, click Build All. The IDE creates the following three files, located in the
same folder as the project .jdp file, for each project:

File extension Description

.cod file the compiled project that is loaded on the BlackBerry device
.csl file a list of required linktime signatures
.cso file a list of signatures that might be required at runtime if the application invokes
controlled methods

2. On the Build menu, click Request signatures.

Warning: If you have already registered for code signing with a previous version of the SDK, back up the following files,
which are located in the BlackBerry JDE bin folder, before you install a new version of the BlackBerry JDE:
• Sigtool.db
• Sigtool.csk
If these files are lost, you must register again with RIM.
3. Click Add.
4. In the Look In drop-down list, click the folder in which the .cod file is located.
5. Click a .cod file.
6. Click Open.
7. Click Request.
8. Type your private key password.
9. Click OK.

Request signatures at a command prompt

1. At the command prompt, move to the folder containing the Signature Tool software.
2. Type the following command line:
java -jar SignatureTool.jar [-a] [-c] [-C] <file>
where:
[-a] is used when you want the program to automatically request signatures.
[-c] is used when you want the program to close after requesting signatures if no errors occur.
[-C] is used when you want the program to close regardless of its success.
<file> can be the name of only one .csi file or one or more .cod files.
• .csi: The .csi file contains client registration information and a list of the signatures that the
client is allowed to apply for. You can only pass in one .csi at a time.
• .cod: The .cod file is the compiled application that can be loaded onto BlackBerry devices after
all required signatures are in place. You can pass in as many .cod files as you want.

9
BlackBerry Application Developer Guide

10
 2
Integrating messages
• Mail API
• Working with messages
• Managing folders
• Managing attachments

Mail API
The BlackBerry mail API, in the net.rim.blackberry.api.mail and
net.rim.blackberry.mail.event packages, enables applications to send, receive, and access
messages using the messages application.
Notes: The BlackBerry mail API provides access to messages in the messages list, but not to other message types, such as
SMS messages, PIN messages, or phone-call logs. For access to phone-call logs, use the Phone Log API
(net.rim.blackberry.api.phonelogs). See “Accessing and managing phone logs” on page 75 for more information.
Check for a NoClassDefFoundError when your application first accesses the Mail API. This error is thrown if the system
administrator restricts access to the Mail API using application control. See “Application control” on page 12 of the
BlackBerry Application Developer Guide Volume 1: Fundamentals for more information.

Mail API classes

Class name Description
Session This class, which represents an abstract model for messaging operations, provides access to messaging service,
storage, and transport. Applications retrieve a new Session object to send or receive messages.
To retrieve a session with the default mail service on the BlackBerry device, invoke
Session.waitForDefaultSession() and wait until the service is available.
To retrieve a session with a different messaging service, create a ServiceConfiguration object for the
messaging service, and invoke Session.getDefaultInstance(ServiceConfiguration).
Store This class models the underlying message storage on the BlackBerry device. To retrieve a Store instance, invoke
the Session instance.
Transport This class represents the messaging transport protocol.

Messages
A Message object consists of a set of attributes, such as subject, sender, and recipients, and a message
body (its contents). See “Multipart messages” on page 12 for more information.
The following classes and interfaces define supported message attributes:

Class or interface name Description

Address This class represents a messaging, ftp, http, or wap address that is used in the from, reply-to, and
recipient attributes, and in the message body. The Address class contains fields to store the fully
qualified address string, such as [email protected], and the display name.
Header This class defines supported header fields, such as TO, FROM, and DATE.
Message.Flag This interface defines message flags, such as MOVED, OPENED, or SAVED.
BlackBerry Application Developer Guide

Class or interface name Description

Message.Icons This interface defines the character representations of the various message status icons, such as
a check mark for a sent message.
Message.RecipientType This interface defines supported recipient types, such as TO, CC, or BCC.
Message.Status This interface defines status options for sending and receiving messages, such as RX_RECEIVED,
RX_ERROR, TX_SENT, and TX_READ.

Multipart messages
The mail API supports multipart messages. The Multipart abstract class provides a container for one or
more BodyPart objects. Multipart provides methods to retrieve and set its subparts.
Each BodyPart consists of header fields (attributes) and contents (body). The mail API provides four
implementations of BodyPart.

Class name Description

ContactAttachmentPart This class represents an address-card attachment part, using the
javax.microedition.pim.Contact interface. See “Using the address book” on page 25 for
more information
TextBodyPart This class represents a body part with content that is text/plain type. You use this class to create
a multipart message that includes a text/plain part.
UnsupportedAttachmentPart This class represents an unsupported attachment part. You cannot instantiate this class. The
content type is always application/octet-stream.
SupportedAttachmentPart This class represents a supported attachment part, for which there is a registered attachment
handler on the BlackBerry device.

Message storage
The Folder class represents a local mailbox folder. Several folder types are defined, including INBOX,
OUTBOX, SENT, and OTHER. You can use these folder types to retrieve folders for retrieving or saving
messages.
The Store class models the underlying message storage and provides methods for finding and retrieving
folders. Folders exist in a hierarchy, as the following example demonstrates:
Mailbox - Aisha Wahl
Inbox
Projects
In Progress
Complete
Personal
A standard delimiter character separates each folder in the hierarchy, which you can retrieve using
getSeparator(). You can list all the folders in a Store object, list the subfolders in a folder, or find a
folder based on a search string.
The Folder class defines methods for retrieving messages or subfolders, saving messages, and deleting
messages.
Note: Multiple Folder instances can refer to the same folder on the BlackBerry device. As a result, you should always invoke
addFolderListener() and removeFolderListener() on the same Folder object. Use Folder.equals() to
determine whether two Folder objects refer to the same folder.

12
 2: Integrating messages

Mail events
The BlackBerry mail event package (net.rim.blackberry.api.mail.event) defines the following
messaging events and listeners for each event:

Event Description
FolderEvent This event triggers when a message in a folder is added or removed.
MessageEvent This event triggers when a message changes (body, header, or flags).
StoreEvent This event triggers when a message is added to, or removed from, the message store in a batch operation
(for example, when the BlackBerry device is synchronized with the desktop).

The MailEvent class is the base class for these mail event classes. The MailEvent class defines an
abstract dispatch() method to invoke the appropriate listener method for each event.
The EventListener interface provides a common interface for the FolderListener and
MessageListener interfaces.

Listener Applicable objects

FolderListener This listener type can be added to Folder or Store object.
MessageListener This listener type can be added to Message object.
StoreListener This listener type can be added to Store object.

Working with messages

Receive message notification
Your implementation of the FolderListener and StoreListener interfaces enables your application
to receive message notification.
public class MailTest implements FolderListener, StoreListener { ... }

Add a listener to the message store

To listen for message store events, such as synchronization, retrieve the Store object and add a
StoreListener instance to it.

try {
Store store = Session.waitForDefaultSession().getStore();
} catch (NoSuchServiceException e) {
System.out.println(e.toString());
}
store.addStoreListener(this);

Your implementation of StoreListener.batchOperation() defines application behavior when

messages are added to or removed from the message store in batch operations. For example, your
application could check if any messages to which it had references were removed.
void batchOperation(StoreEvent e) {
// Perform action when messages added or removed in batch operation.
}

13
BlackBerry Application Developer Guide

Add a listener to a folder

To listen for folder events, such as the addition of a message to a particular folder, retrieve the Folder
object for which you want to receive notifications of new messages. Add the FolderListener instance
to the folder.
Folder[] folders = store.list(Folder.INBOX);
Folder inbox = folders[0];
inbox.addFolderListener(this);

Your implementations of FolderListener.messagesAdded() and

FolderListener.messagesRemoved() perform actions when folder events occur. For example, you
could implement these methods to maintain the consistency of any references your application had to
specific mail folders.
void messagesAdded(FolderEvent e) {
// Perform processing on added messages.
}
void messagesRemoved(FolderEvent e) {
// Perform processing on removed messages.
}

Receive more of a message

By default, the first section of a message (typically about 2 KB) is sent to the BlackBerry device. Invoke
hasMore() on a body part to determine whether more data is available on the server. Invoke
moreRequestSent() to determine whether a request for more data has already been sent. Invoke
more() to request more of a message.

if (( bp.hasMore() ) && (! bp.moreRequestSent()) {

Transport.more(bp, true);
}

The second parameter of more() is a Boolean value that specifies whether to retrieve only the next
section of the body part (false) or all remaining sections of the body part (true).

Open a message
Retrieve the message store and the folder that contains the message.
Store store = Session.waitForDefaultSession.getStore();
Folder folder = Store.getFolder("SampleFolder");

Retrieve the message objects from the folder. Iterate through the array and retrieve information, such as
the sender and subject, to display to the user.
Message[] msgs = folder.getMessages();

When a user selects a message from the list, invoke methods on the Message object to retrieve the
appropriate fields and body contents to display to the user.
Message msg = msgs[0]; // Retrieve the first message.
Address[] recipients = msg.getRecipients(Message.RecipientType.TO)
Date sent = msg.getSentDate();
Address from = msg.getFrom();
String subject = msg.getSubject();

14
 2: Integrating messages

Object o = msg.getContent();
// Verify that the message is not multipart.
if ( o instanceof String ) {
String body = (String)o;
}
//...

Note: Invoke getBodyText() on a message to retrieve the plain text contents as a String. If the message does not
contain plain text, the method returns null.

Send a message
To send messages, use a Transport object, which represents the messaging transport protocol.

Create a message
Create a Message object, and specify a folder in which to save a copy of the sent message.
Store store = Session.getDefaultInstance().getStore();
Folder[] folders = store.list(Folder.SENT);
Folder sentfolder = folders[0];
Message msg = new Message(sentfolder);

Specify recipients
Create an array of Address objects, and then add each address to the array. Your application should
catch an AddressException, which is thrown if an address is invalid.
Address toList[] = new Address[1];
try {
toList[0]= new Address("[email protected]", "Aisha Wahl");
} catch(AddressException e) {
System.out.println(e.toString());
}

Add recipients
Invoke Message.addRecipients(). Provide the type of recipient (TO, CC, or BCC) and the array of
addresses to add as parameters to this method. If your message has multiple types of recipients, invoke
addRecipients() once each.

msg.addRecipients(Message.RecipientType.TO, toList);

Specify the name and internet messaging address of a sender

Invoke setFrom(Address).
Address from = new Address("[email protected]", "Scott McPherson");
msg.setFrom(from);

Add a subject line

Invoke setSubject(String).
msg.setSubject("Test Message");

15
BlackBerry Application Developer Guide

Specify the message contents

Invoke setContent(String). Typically, your application retrieves content from text that a user types in
a field.
try {
msg.setContent("This is a test message.");
} catch(MessagingException e) {
System.out.println(e.getMessage());
}

Send the message

Invoke Transport.send(Message).
try {
Transport.send(msg);
} catch(MessagingException e) {
System.out.println(e.getMessage());
}

Reply to a message
To create a message as a reply to an existing message, invoke Message.reply(Boolean). As a
parameter to this method, specify true to reply to all message recipients or false to reply only to the
sender.
Store store = Session.waitForDefaultSession().getStore();
Folder[] folders = store.list(INBOX);
Folder inbox = folders[0];
Message[] messages = folder.getMessages();
if( messages.length > 0 ) {
Message msg = messages[0];
}
Message reply = msg.reply(true);
Transport.send(reply);

Forward a message
Invoke forward() on an existing Message object.
Note: The subject line of a forwarded message is set automatically to FW:<original_subject>.

Message fwdmsg = msg.forward();

Add recipients
Create an array of addresses, and then invoke addRecipients(int, Address[]).
Address toList[] = new Address[1];
toList[0]= new Address("[email protected]", "Katie Laird");
fwdmsg.addRecipients(Message.RecipientType.TO, toList);

16
 2: Integrating messages

Specify message contents

Invoke setContent(String).
Note: You cannot edit the text of the forwarded message. The setContent() method adds text before the forwarded
message.

try {
fwdmsg.setContent("This is a forwarded message.");
} catch(MessagingException e) {
System.out.println(e.getMessage());
}

Send the message

Invoke send(Message).
try {
Transport.send(fwdmsg);
} catch(MessagingException e) {
System.out.println(e.getMessage());
}

Code example
Example: BasicMail.java
/**
* BasicMail.java
* Copyright (C) 2001-2005 Research In Motion Limited.
*/

package com.rim.samples.docs.basicmail;

import net.rim.blackberry.api.mail.*;
import net.rim.blackberry.api.mail.event.*;
import net.rim.device.api.system.*;

public class BasicMail extends Application {

private Store store;
static void main (String args[]) {
BasicMail app = new BasicMail();
app.enterEventDispatcher();
}
BasicMail() {
Store store = Session.getDefaultInstance().getStore();
Folder[] folders = store.list(Folder.SENT);
Folder sentfolder = folders[0];
// Create message.
Message msg = new Message(sentfolder);
// Add TO Recipients.
Address toList[] = new Address[1];
try {
toList[0]= new Address("[email protected]", "Scott Tooke");
} catch(AddressException e) {
System.out.println(e.toString());

17
BlackBerry Application Developer Guide

}
try {
msg.addRecipients(Message.RecipientType.TO, toList);
} catch (MessagingException e) {
System.out.println(e.toString());
}
// Add CC Recipients.
Address ccList[] = new Address[1];
try {
ccList[0]= new Address("[email protected]", "Katie Laird");
} catch(AddressException e) {
System.out.println(e.toString());
}
try {
msg.addRecipients(Message.RecipientType.CC, ccList);
} catch (MessagingException e) {
System.out.println(e.toString());
}
// Add the subject.
msg.setSubject("A Test Email");
// Add the message body.
try {
msg.setContent("This is a test message.");
} catch(MessagingException e) {
// Handle messaging exceptions.
}
// Send the message.
try {
Transport.send(msg);
} catch(MessagingException e) {
System.out.println(e.getMessage());
}
System.out.println("Email sent successfully.");
System.exit(0);

}
}

Managing folders
To list, retrieve, and search for folders, retrieve a Store object by invoking getStore() on the default
session.
Store store = Session.waitForDefaultSession().getStore();

List the folders in a mailbox store

Invoke Store.list().
Folder[] folders = store.list();

18
 2: Integrating messages

Retrieve an array of folders by type

Invoke list(int). Provide the folder type as a parameter to this method.
Folder[] folders = store.list(INBOX);
Folder inbox = folders[0];

Retrieve an array of folders by searching

To retrieve all the folders in the hierarchy that match a specified search string, invoke
findFolder(String).

Folder[] folders = store.findFolder("Inbox");

The findFolder(String) method returns an array of folders that match the specified string, or an
empty array if a matching folder is not found.

Retrieve a folder by name

Invoke getFolder(String). Provide as a parameter the absolute path to the folder. A
FolderNotFoundException exception is thrown if the folder is not found.

Folder folder = store.getFolder("Mailbox - Aisha Wahl/Inbox/Projects");

Retrieve a folder by ID
Invoke getID() to retrieve the folder ID, and then invoke getFolder() with the ID as a parameter.
Folder[] folders = store.list();
long id = folders[0].getId();
Folder f2 = store.getFolder(id);

File a message
Invoke appendMessage(Message) on a Folder object.
Message msg = new Message();
//...
Folder folder = store.getFolder("Inbox");
folder.appendMessage(msg);

Managing attachments
The mail API enables you to open incoming message attachments and to create outgoing attachments
on the BlackBerry device. A message attachment is represented as a separate BodyPart on a Multipart
message.

19
BlackBerry Application Developer Guide

Create a custom attachment handler

Your implementation of the AttachmentHandler interface defines a custom attachment handler.

Register accepted MIME types

Your implementation of supports(String) registers the MIME type of attachments that your
attachment handler accepts. This method is invoked when the BlackBerry device receives an attachment.
public boolean supports(String contentType) {
return (contentType.toLowerCase().indexOf("contenttype") != -1 ? true : false);
}

Define the associated menu item string

Your implementation of menuString() returns the menu item string to display in the messages list
when the user selects an attachment.
public String menuString() {
return "Custom Attachment Viewer";
}

Define attachment processing

Your implementation of run() performs the appropriate processing on the attachment data and display
it to the user.
public void run(Message m, SupportedAttachmentPart p) {
// Perform processing on data.
Screen view = new Screen();
view.setTitle(new LabelField("Attachment Viewer"));
view.add(new RichTextField(new String((byte[])p.getContent())));
}
Note: The run() method is invoked when the corresponding menu item is selected in the messages list.

Register an attachment handler

The AttachmentHandlerManager class controls how attachments are processed on the BlackBerry
device. To enable the message application to invoke your custom attachment when the user opens an
attachment of the associated type, register your attachment handler by invoking
addAttachmentHandler().
Note: The BlackBerry Enterprise Server Attachment Service has first priority in receiving attachments. Third-party
attachment handlers cannot override default BlackBerry device behavior. See the BlackBerry Enterprise Server Maintenance
and Troubleshooting Guide for more information.

AttachmentHandlerManager m = AttachmentHandlerManager.getInstance();
CustomAttachmentHandler ah = new CustomAttachmentHandler();
m.addAttachmentHandler(ah);

Retrieving attachments
The SupportedAttachmentPart class represents an attachment with a corresponding viewer on the
BlackBerry device. An attachment that does not have a viewer on the BlackBerry device is represented as
an UnsupportedAttachmentPart.

20
 2: Integrating messages

Retrieve attachment contents

Invoke getContent().
String s = new String((byte[])p.getContent());

Retrieve attachment information

The SupportedAttachmentPart class provides several methods to retrieve attachment information. The
following example invokes getName() and getSize() to retrieve the attachment name and size.
public void run(Message m, SupportedAttachmentPart p) {
...
String name = p.getName();
int size = p.getSize();
}

Send a message with an attachment

Create a multipart message by creating a new Multipart object. To create each attachment
component, create a SupportedAttachmentPart object, designating the Multipart as its parent. To
add each SupportedAttachmentPart to the Multipart, invoke
addBodyPart(SupportedAttachmentPart) on that object.
When you invoke setContent(Multipart) on the Message object, pass in the Multipart object as its
parameter.
byte[] buf = new byte[256]; // The attachment.
MultiPart multipart = new MultiPart(); // Default type of multipart/mixed.
SupportedAttachmentPart attach = new SupportedAttachmentPart( multipart,
"application/x-example", "filename", data);
multipart.addBodyPart(attach); // Add the attachment to the multipart.
msg.setContent(multipart);
Transport.send(msg); // Send the message.

21
BlackBerry Application Developer Guide

22
 3
Integrating PIM functions
• PIM APIs
• Using the address book
• Using tasks
• Using the calendar

PIM APIs
The Java personal information management (PIM) APIs (javax.microedition.pim) and the BlackBerry
personal digital assistant profile (PDAP) APIs (net.rim.blackberry.api.pdap) enable you to access
the calendar, tasks, and address book on the BlackBerry device.
Note: As of version 4.0, the net.rim.blackberry.api.pim package is deprecated. The classes from this package are
now available in the javax.microedition.pim and net.rim.blackberry.api.pdap packages.

The PIM class is an abstract class that provides methods for accessing PIM databases on the BlackBerry
device. Invoke PIM.getInstance() to retrieve a PIM object.
Note: Check for a ControlledAccessException when your application first accesses the PIM API. This runtime exception
is thrown if the system administrator restricts access to the PIM API using application control. See the BlackBerry
Application Developer Guide Volume 1: Fundamentals for more information.

PIM lists
The PIMList interface represents the common functionality of all contact, event, or task lists. A list
contains zero or more items, represented by subclasses of PIMItem. Use PIM lists to organize related
items and to retrieve some or all of the items in the list.
Note: On BlackBerry devices, each ContactList, ToDoList, or EventList instance refers to the native database on the
BlackBerry device. Third-party applications cannot create custom lists.

PIM items
The PIMItem interface represents the common functionality of an item in a list. The Contact, Event,
and ToDo interfaces extend PIMItem. A PIM item represents a collection of data for a single entry, such
as a calendar appointment or a contact.
When you create a PIM item in a particular PIM list, the item remains associated with that list as long as
it exists. You can also import or export data in PIM items using standard formats, such as iCal and vCard.

Fields
A PIM item stores data in fields.
Each PIMItem interface—Contact, Event, or ToDo—defines unique integer IDs for each field that it
supports. For example, the Contact interface defines fields to store an internet messaging address
(EMAIL), name (FORMATTED_NAME), and phone number (TEL).
BlackBerry Application Developer Guide

Each field has a data type ID, such as INT, BINARY, DATE, BOOLEAN, or STRING. To retrieve the data type
of a field, invoke PIMList.getFieldDataType(int). The data type determines which method you use
to get or set field data. For example, if the data type for a field is STRING, invoke
PIMItem.addString(String) to add a value, PIMItem.setString(String) to change an existing
value, and PIMItem.getString() to retrieve a value.
Before you attempt to set or retrieve a field value, verify that the method supports the field by invoking
PIMList.isSupportedField(int).
A field can have an associated descriptive label to display to users. To retrieve a field label, invoke
PIMList.getFieldLabel(int).

Listeners
Your implementation of the PIMListListener interface receives notification when an item in a list
changes. The PIMListListener interface provides three methods:

Method Description
itemAdded(PIMItem) invoked when an item is added to a list
itemRemoved(PIMItem) invoked when an item is removed from a list
itemUpdated(PIMItem, PIMItem) invoked when an item changes

ContactList cl = (ContactList)PIM.getInstance().openPIMList(
PIM.CONTACT_LIST, PIM.WRITE_ONLY);
((BlackBerryPIMList)cl).addListener(new PIMListListener() {
public void itemAdded(PIMItem item) {
System.out.println(" ITEM ADDED: " + ((Contact)item).getString(Contact.UID,
0));
}
public void itemUpdated(PIMItem oldItem, PIMItem newItem) {
System.out.println(" ITEM UPDATED: " +
((Contact)oldItem).getString(Contact.UID, 0) + " to " +
((Contact)newItem).getString(Contact.UID, 0));
}
public void itemRemoved(PIMItem item) {
System.out.println(" ITEM REMOVED: " +
((Contact)item).getString(Contact.UID, 0));
}
});

Note: The listener remains associated with the BlackBerry device database even after the corresponding PIMList object
has been deleted. To remove the listener, invoke BlackBerryPIMList.removeListener().

Remote address lookup

Applications that support remote address lookup should instantiate the BlackBerryContactList
interface, which extends the ContactList interface and provides the following additional methods:

Method Description
choose(Contact, int, boolean) Launches the address book so that the user can select an address.
void lookup(Contact, RemoteLookupListener) Initiates a remote lookup.
void lookup(String, RemoteLookupListener) Initiates a remote lookup.

The RemoteLookupListener interface provides a single method, items(), which returns an

enumeration of the results of a remote address lookup.

24
 3: Integrating PIM functions

Using the address book

Use an instance of ContactList to add or view contact information in the BlackBerry device address
book. Create Contact objects to store individual contacts with information, such as name, phone
number, internet messaging address, and street address.

BlackBerry-specific address fields

The BlackBerryContact interface, which extends Contact, defines the following constants to provide
access to fields that are specific to BlackBerry contacts:

Constant Description
BlackBerryContact.PIN provides access to the PIN field
BlackBerryContact.USER1 through provide access to the USER1 through USER4 fields
USER4

Invoke BlackBerryPIMList.setFieldLabel() to define labels for the USER1 through USER4 fields.
The change takes effect immediately; you do not need to commit the change.

Note: Changing a label affects all contacts on the BlackBerry device.

Open a contact list

You must create a contact list before you can add contacts. Invoke PIM.openPIMList(). Provide as
parameters the type of list to open (PIM.CONTACT_LIST) and the access mode with which to open the
list (READ_WRITE, READ_ONLY, or WRITE_ONLY).
If you are writing an application specifically for BlackBerry devices, cast your contact list as a
BlackBerryContactList because this interface provides additional methods to support remote
address lookup. To make an application portable across multiple J2ME-compatible BlackBerry devices,
use the PDAP implementation.
ContactList contactList = null;
try {
contactList = (ContactList)PIM.getInstance().openPIMList(
PIM.CONTACT_LIST, PIM.READ_WRITE);
} catch (PimException e) {
return;
}

Create a contact
Invoke createContact() on a contact list.
Contact contact = contactList.createContact();
Note: The contact is not added to the database until you commit it. See “Save a contact” on page 27 for more information.

25
BlackBerry Application Developer Guide

Add contact information

The Contact class defines fields in which to store data, such as Contact.NAME, Contact.ADDR, and
Contact.TEL. Each field has a specific data type, which you can retrieve by invoking
PIMList.getFieldDataType(int). Depending on the data type of the field, add a new value by
invoking one of the following methods: addString(), addStringArray(), addDate(), addInt(),
addBoolean(), or addBinary().
Before you set or retrieve a field, verify that the item supports the field by invoking
ContactList.isSupportedField(int).
Some fields can store multiple values, using attributes to differentiate between values. For example, the
TEL field supports the ATTR_HOME, ATTR_WORK, ATTR_MOBILE, and ATTR_FAX attributes to store
numbers for work, home, mobile, and fax numbers. To determine how many values a field supports,
invoke PIMList.maxValues(int field). This method returns the number of values supported, or -1
to indicate that an arbitrary number of values can be added. To verify that a field supports a particular
attribute, invoke isSupportedAttribute(int, int).
// Create string array for name.
try {
ContactList contactList =
(ContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST,
PIM.WRITE_ONLY);
} catch (PIMException e) {
}
Contact contact = contactList.createContact();
String[] name = new String[5]; // 5 name elements
try {
name[Contact.NAME_PREFIX] = "Mr.";
name[Contact.NAME_FAMILY] = "McPherson";
name[Contact.NAME_GIVEN] = "Scott";
} catch (IllegalArgumentException iae) {
// handle exception
}
// Add name.
if(contactList.isSupportedField(Contact.NAME)) {
contact.addStringArray(Contact.NAME, Contact.ATTR_NONE, name);
}
// Create string array for address.
String[] address = new String[7]; // 7 address elements
try {
address[Contact.ADDR_COUNTRY] = "United States";
address[Contact.ADDR_LOCALITY] = "Los Angeles";
address[Contact.ADDR_POSTALCODE] = "632300";
address[Contact.ADDR_REGION] = "California";
address[Contact.ADDR_STREET] = "323 Main Street";
} catch (IllegalArgumentException iae) {
// Handle exception.
}
// Add address.
contact.addStringArray(Contact.ADDR, Contact.ATTR_NONE, address);
// Add home telephone number.
if (contactList.isSupportedField(Contact.TEL) &&
contactList.isSupportedAttribute(Contact.TEL, Contact.ATTR_HOME)) {
contact.addString(Contact.TEL, Contact.ATTR_HOME, "555-1234");
}

26
 3: Integrating PIM functions

// Add work telephone number.

if (contactList.isSupportedField(Contact.TEL)) {
contact.addString(Contact.TEL, Contact.ATTR_HOME, "555-5555");
}
// Add work internet messaging address.
if (contactList.isSupportedField(Contact.EMAIL)) {
contact.addString(Contact.EMAIL, Contact.ATTR_WORK,
"[email protected]");
}

Modify contact information

For fields that support only one value, invoke the appropriate set method to replace an existing value
with a new value.
Note: If you invoke an add method, such as addString(), for a field that already has a value, a FieldFullException is
thrown. Use the corresponding set method, such as setString(), to change an existing value.
For the name and address fields, which contain a string array value, retrieve the array and then modify
one or more indexes in the array before adding it back in.
if (contact.countValues(Contact.NAME) > 0) {
String[] newname = contact.getStringArray(Contact.NAME, 0);
}
// Change the prefix to Dr. and add the suffix, Jr.
newname[Contact.NAME_PREFIX] = "Dr.";
newname[Contact.NAME_SUFFIX] = "Jr.";
contact.setStringArray(Contact.NAME, 0, Contact.ATTR_NONE, newname);

For fields that support multiple values, verify that the maximum number of values is not exceeded before
adding another value.
if (contact.countValues(Contact.EMAIL) < contactList.maxValues(Contact.EMAIL)) {
contact.addString(Contact.EMAIL, Contact.ATTR_NONE,
"[email protected]");
}

Save a contact
Invoke commit(). Before you commit the change, invoke isModified() to determine whether any
contact fields have changed since the contact was last saved.
if(contact.isModified()) {
contact.commit();
}

Retrieve contact information

Invoke PIMList.items().
Note: When you invoke PIMList.items() to retrieve an enumeration of items in a list, the order of items is undefined.
Your application must sort items as necessary.

27
BlackBerry Application Developer Guide

For a particular contact, invoke PIMItem.getFields() to retrieve an array of IDs for fields that have
data. Invoke PIMItem.getString() to retrieve the field values.
ContactList contactList = (ContactList)PIM.getInstance().openPIMList(
PIM.CONTACT_LIST, PIM.READ_WRITE);
Enumeration enum = contactList.items();
while (enum.hasMoreElements()) {
Contact c = (Contact)enum.nextElement();
int[] fieldIds = c.getFields();
int id;
for(int index = 0; index < fieldIds.length; ++index) {
id = fieldIds[index];
if(c.getPIMList().getFieldDataType(id) == Contact.STRING) {
for(int j=0; j < c.countValues(id); ++j) {
String value = c.getString(id, j);
System.out.println(c.getPIMList().getFieldLabel(id) + "=" + value);
}
}
}
}

Convert a contact to a serial format

To import or export PIM item data, use an output stream writer to export tasks from the BlackBerry
device to a supported serial format, such as vCard.
To retrieve a string array of supported formats, invoke PIM.supportedSerialFormats() and specify
the list type (PIM.Contact_LIST).
To write an item to a supported serial format, invoke toSerialFormat().
Note: The enc parameter specifies the character encoding to use when writing to the output stream. Supported character
encodings include "UTF8," "ISO-8859-1," and "UTF-16BE." This parameter cannot be null.

ContactList contactList = (ContactList)PIM.getInstance().openPIMList(

PIM.CONTACT_LIST, PIM.READ_ONLY);
String[] dataFormats = PIM.getInstance().supportedSerialFormats(
PIM.CONTACT_LIST);
ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
Enumeration e = contactList.items();
while (e.hasMoreElements()) {
Contact c = (Contact)e.nextElement();
PIM.getInstance().toSerialFormat(c, byteStream, "UTF8", dataFormats[0]);
}

Import a contact
Invoke fromSerialFormat(), which returns an array of PIM items. To create a new contact using the
PIM item, invoke ContactList.importContact()
Note: The enc parameter specifies the character encoding to use when writing to the output stream. Supported character
encodings include "UTF8," "ISO-8859-1," and "UTF-16BE." This parameter cannot be null.

// Import contact from vCard.

ByteArrayInputStream is = new ByteArrayInputStream(outputStream.toByteArray());

28
 3: Integrating PIM functions

PIMItem[] pi = PIM.getInstance().fromSerialFormat(istream, "UTF8");

ContactList contactList =
(ContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
Contact contact2 = contactList.importContact((Contact)pi[0]);
contact2.commit();

Delete a contact
Invoke removeContact() on a contact list.
contactList.removeContact(contact);

Close a contact list

Invoke close().
try {
contactList.close();
} catch(PIMException e) {
Dialog.alert(e.toString());
}

Code example
The following example demonstrates how to display a screen that enables users to add new contacts to
the address book. After you save a contact, open the address book to verify that the contact was saved.

Example: ContactsDemo.java
/**
* ContactsDemo.java
* Copyright (C) 2002-2005 Research In Motion Limited.
*/

package com.rim.samples.docs.contactsdemo;

import java.io.*;
import java.util.*;
import javax.microedition.pim.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.i18n.*;
import net.rim.device.api.system.*;
import net.rim.device.api.util.*;
import com.rim.samples.docs.baseapp.*;
import net.rim.blackberry.api.pdap.*;

public final class ContactsDemo extends BaseApp {

private ContactScreen _contactScreen;
public static void main(String[] args) {
new ContactsDemo().enterEventDispatcher();

29
BlackBerry Application Developer Guide

}
public ContactsDemo() {
_contactScreen = new ContactScreen();
pushScreen(_contactScreen);
}
protected void onExit() {
}
// Inner class. Creates a Screen to add a contact.
public static final class ContactScreen extends MainScreen {
private EditField _first, _last, _email, _phone, _pin;
private SaveMenuItem _saveMenuItem;
private class SaveMenuItem extends MenuItem {
private SaveMenuItem() {
super(null, 0, 100000, 5);
}
public String toString() {
return "Save";
}
public void run() {
onSave();
}
}
public ContactScreen() {
_saveMenuItem = new SaveMenuItem();
setTitle(new LabelField("Contacts Demo", LabelField.ELLIPSIS |
LabelField.USE_ALL_WIDTH));
_first = new EditField("First Name: ", "");
add(_first);
_last = new EditField("Last Name: ", "");
add(_last);
_email = new EditField("Email Address: ", "",
BasicEditField.DEFAULT_MAXCHARS, BasicEditField.FILTER_EMAIL);
add(_email);
_phone = new EditField("Work Phone: ", "",
BasicEditField.DEFAULT_MAXCHARS, BasicEditField.FILTER_PHONE);
add(_phone);
_pin = new EditField("PIN:", "", 8, BasicEditField.FILTER_HEXADECIMAL);
add(_pin);
}
protected boolean onSave() {
String firstName = _first.getText();
String lastName = _last.getText();
String email = _email.getText();
String phone = _phone.getText();
String pin = _pin.getText();
// Verify that a first or last name and email has been entered.
if ((firstName.equals("") && lastName.equals("")) || email.equals("")) {
Dialog.inform("You must enter a name and an email address!");
return false;
} else {
try {
ContactList contactList =
(ContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.WRITE_ONLY);
Contact contact = contactList.createContact();
String[] name = new
String[contactList.stringArraySize(Contact.NAME)];

30
 3: Integrating PIM functions

// Add values to PIM item.

if (!firstName.equals("")) {
name[Contact.NAME_GIVEN] = firstName;
}
if (!lastName.equals("")) {
name[Contact.NAME_FAMILY] = lastName;
}
contact.addStringArray(Contact.NAME, Contact.ATTR_NONE, name);
contact.addString(Contact.EMAIL, Contact.ATTR_HOME, email);
contact.addString(Contact.TEL, Contact.ATTR_WORK, phone);
if (contactList.isSupportedField(BlackBerryContact.PIN)) {
contact.addString(BlackBerryContact.PIN, Contact.ATTR_NONE,
pin);
}
// Save data to address book.
contact.commit();
// Reset UI fields.
_first.setText("");
_last.setText("");
_email.setText("");
_phone.setText("");
_pin.setText("");
return true;
} catch (PIMException e) {
return false;
}
}
}
protected void makeMenu(Menu menu, int instance) {
menu.add(_saveMenuItem);
super.makeMenu(menu, instance);
}
}
}

Using tasks
Use an instance of the ToDoList class to store a list of tasks or to-do items. Create one or more ToDo
objects to store data for each task, such as summary, priority, due date, and status.

Open a task list

Invoke PIM.openPIMList(). Provide as parameters the type of list to open (PIM.TODO_LIST) and the
access mode with which to open the list (READ_WRITE, READ_ONLY, or WRITE_ONLY).
ToDoList todoList = null;
try {
todoList = (ToDoList)PIM.getInstance().openPIMList(
PIM.TODO_LIST, PIM.READ_WRITE);
} catch (PimException e) {
//an error occurred

31
BlackBerry Application Developer Guide

return;
}

Create a task
Invoke createToDo() on a task list.
ToDo task = todoList.createToDo();
Note: The task is not added to the database until you commit it. See “Save a task” on page 33 for more information.

Add task information

The ToDo class defines fields in which to store data, such as SUMMARY, PRIORITY, and DUE. Each field has
a specific data type, which you can retrieve by invoking PIMList.getFieldDataType(int).
Depending on the data type of the field, set the field data by invoking one of the following methods:
addString(), addDate(), addInt(), addBoolean(), or addBinary().
See “PIM APIs” on page 23 for more information on fields.
Before you set or retrieve a field, verify that the item supports the field by invoking
isSupportedField(int).

if (task.isSupportedField(ToDo.SUMMARY)) {
task.addString(ToDo.SUMMARY, ToDo.ATTR_NONE, "Create project plan");
}
if (task.isSupportedField(ToDo.DUE)) {
Date date = new Date();
task.addDate(ToDo.DUE, ToDo.ATTR_NONE, (date + 17280000));
}
if (task.isSupportedField(ToDo.NOTE)) {
task.addString(ToDo.NOTE, ToDo.ATTR_NONE, "Required for meeting");
}
if (task.isSupportedField(ToDo.PRIORITY)) {
task.addInt(Todo.PRIcORITY, ToDo.ATTR_NONE, 2);
}

Set the status of a task

Use the PIM extended field ToDo.EXTENDED_FIELD_MIN_VALUE + 9.

Constant Value
STATUS_NOT_STARTED 1
STATUS_IN_PROGRESS 2
STATUS_COMPLETED 3
STATUS_WAITING 4
STATUS_DEFERRED 5

task.addInt(ToDo.EXTENDED_FIELD_MIN_VALUE + 9, ToDo.ATTR_NONE, 2);

32
 3: Integrating PIM functions

Modify task information

Invoke the appropriate set method, such as setString(), to replace an existing value with a new
value. Invoke countValues() to determine if a value is already set for the field.
Note: If you invoke an add method, such as addString(), when a value already exists, a FieldFullException is thrown.
Use the corresponding set method, such as setString(), to change an existing value.

if (task.countValues(ToDo.SUMMARY) > 0) {
task.setString(ToDo.SUMMARY, 0, ToDo.ATTR_NONE, "Review notes");
}

Save a task
Invoke commit(). Before you save, invoke isModified() to determine whether any task fields have
changed since the task was last saved.
if(task.isModified()) {
task.commit();
}

Retrieving task information

Retrieve an enumeration
Invoke PIMList.items() on the task list.
ToDoList todoList = (ToDoList)PIM.getInstance().openToDoList(
PIM.TODO_LIST, PIM.READ_ONLY);
Enumeration enum = todoList.items();

Retrieve field IDs and values for a task

To retrieve an array of IDs for fields that have data for a particular ToDo item, invoke
PIMItem.getFields(). To retrieve the field values, invoke PIMItem.getString().

while (enum.hasMoreElements()) {
ToDo task = (ToDo)enum.nextElement();
int[] fieldIds = task.getFields();
int id;
for(int index = 0; index < fieldIds.length; ++index) {
id = fieldIds[index];
if(task.getPIMList().getFieldDataType(id) == STRING) {
for(int j=0; j < task.countValues(id); ++j) {
String value = task.getString(id, j);
System.out.println(task.getFieldLable(id) + "=" + value);
}
}
}
}

33
BlackBerry Application Developer Guide

Convert a task to a to serial format

To import or export PIM item data, use an output stream writer to export tasks from the BlackBerry
device to a supported serial format.
To retrieve a string array of supported serial formats, invoke PIM.supportedSerialFormats(), and
then specify the list type (PIM.TODO_List).
To write an item to a serial format, invoke toSerialFormat().
Note: The enc parameter specifies the character encoding to use when writing to the output stream. Supported character
encodings include "UTF8," "ISO-8859-1," and "UTF-16BE." This parameter cannot be null.

ToDoList todoList = (ToDoList)PIM.getInstance().openPIMList(

PIM.TODO_LIST, PIM.READ_ONLY);
ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
String[] dataFormats = PIM.getInstance().supportedSerialFormats(PIM.TODO_LIST);
Enumeration e = todoList.items();
while (e.hasMoreElements()) {
ToDo task = (ToDo)e.nextElement();
PIM.getInstance().toSerialFormat(task, byteStream, "UTF8", dataFormats[0]);
}

Import a task
Invoke fromSerialFormat(), which returns an array of PIMItem objects. To create a new task using the
PIM items, invoke ToDoList.importToDo().
Note: The enc parameter specifies the character encoding to use when writing to the output stream. Supported character
encodings include "UTF8," "ISO-8859-1," and "UTF-16BE." This parameter cannot be null.

String[] dataFormats = PIM.toDoSerialFormats();

// Write task to serial format.
ByteArrayOutputStream os = new ByteArrayOutputStream();
PIM.getInstance().toSerialFormat(task, os, "UTF8", dataFormats[0]);
// Import task from serial format.
ByteArrayInputStream is = new ByteArrayInputStream(outputStream.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(is, "UTF8");
ToDoList todoList = (ToDoList)PIM.getInstance().openPIMList(
PIM.TODO_LIST, PIM.READ_WRITE);
ToDo task2 = todoList.importToDo((ToDo)pi[0]);
Tip: The importToDo() method saves the task, so you do not have to invoke commit().

Delete a task
Invoke removeToDo() on a task list.
todoList.removeToDo(task);

Close a task list

Invoke todoList.close(). Be sure to catch applicable exceptions.
try {

34
 3: Integrating PIM functions

todoList.close();
} catch (PimException e) {
// Handle exception.
}

Code example
Example: TaskDemo.java
/**
* TaskDemo.java
* Copyright (C) 2002-2005 Research In Motion Limited.
*/

package com.rim.samples.docs.taskdemo;
import java.io.*;
import java.util.*;
import javax.microedition.pim.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.i18n.*;
import net.rim.device.api.system.*;
import net.rim.device.api.util.*;
import com.rim.samples.docs.baseapp.*;

public final class TaskDemo extends BaseApp {

private TaskScreen _taskScreen;
public static void main(String[] args) {
new TaskDemo().enterEventDispatcher();
}
private TaskDemo() {
_taskScreen = new TaskScreen();
pushScreen(_taskScreen);
}
protected void onExit() {
}
public final static class TaskScreen extends MainScreen {
// Members.
private EditField _summary, _note;
private DateField _due;
private ObjectChoiceField _priority, _status;
private SaveMenuItem _saveMenuItem;
private class SaveMenuItem extends MenuItem {
private SaveMenuItem() {
super(null, 0, 100000, 5);
}
public String toString() {
return "Save";
}
public void run() {
onSave();
}
}

35
BlackBerry Application Developer Guide

public TaskScreen() {
_saveMenuItem = new SaveMenuItem();
setTitle(new LabelField("Tasks Demo",
LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH));
_summary = new EditField("Task Summary: ", "");
add(_summary);
// In TODO.Priority, 0 to 9 is highest to lowest priority.
String[] choices = {"High", "Normal", "Low"};
_priority = new ObjectChoiceField("Priority: ", choices, 1);
add(_priority);
String[] status = { "Not Started", "In Progress", "Completed",
"Waiting on someone else", "Deferred" };
_status = new ObjectChoiceField("Status: ", status, 0);
add(_status);
_due = new DateField("Due: ", System.currentTimeMillis() + 3600000,
DateField.DATE_TIME);
add(_due);
_note = new EditField("Extra Notes: ", "");
add(_note);
}
protected boolean onSave() {
try {
ToDoList todoList = (ToDoList)PIM.getInstance().
openPIMList(PIM.TODO_LIST, PIM.WRITE_ONLY);
ToDo task = todoList.createToDo();
task.addDate(ToDo.DUE, ToDo.ATTR_NONE, _due.getDate());
task.addString(ToDo.SUMMARY, ToDo.ATTR_NONE, _summary.getText());
task.addString(ToDo.NOTE, ToDo.ATTR_NONE, _note.getText());
task.addInt(ToDo.PRIORITY, ToDo.ATTR_NONE,
_priority.getSelectedIndex());
// ToDo.EXTENDED_FIELD_MIN_VALUE + 9 represents status.
// Add 1 to selected index so that values are correct.
// See the RIM Implementation Notes in the API docmentation for
ToDo.
task.addInt(ToDo.EXTENDED_FIELD_MIN_VALUE + 9, ToDo.ATTR_NONE,
_status.getSelectedIndex() + 1);
// Save task to handheld tasks.
task.commit();
_summary.setText("");
_note.setText("");
_due.setDate(null);
_priority.setSelectedIndex(1); // Reset to “Normal” priority.
_status.setSelectedIndex(0); // Reset to “Not Started” status.
return true;
} catch (PIMException e) {
return false;
}
}
protected void makeMenu(Menu menu, int instance) {
menu.add(_saveMenuItem);
super.makeMenu(menu, instance);
}
}
}

36
 3: Integrating PIM functions

Using the calendar

Use an instance of the EventList class to access the calendar. Create one or more Event objects to
store information for specific appointments. For each event, you can store data such as the summary,
location, start and end time, and reminder notification.

Open an event list

You must create an EventList before you can add events. Invoke PIM.openPIMList(). Provide as
parameters the type of list to open (PIM.EVENT_LIST) and the mode in which to open the list
(READ_WRITE, READ_ONLY, or WRITE_ONLY).
EventList eventList = null;
try {
eventList = (EventList)PIM.getInstance().openPIMList(
PIM.EVENT_LIST, PIM.READ_WRITE);
} catch (PimException e) {
// Handle exception.
}

Create an appointment
Invoke createEvent() on an event list.
Event event = eventList.createEvent();
Note: The appointment is not added to the database until you commit the change. See “Save an appointment” on page
38 for more information.

Add appointment information

The Event class defines fields in which to store data, such as SUMMARY, LOCATION, START, END, and
ALARM. Each field has a specific data type, which you can retrieve by invoking
PIMList.getFieldDataType(int). Depending on the data type of the field, set the field data by
invoking one of the following methods: addString(), addDate(), addInt(), addBoolean(), or
addBinary().
Before you set or retrieve a field, verify that the item supports the field by invoking
isSupportedField(int).

if (event.isSupportedField(Event.SUMMARY)) {
event.addString(Event.SUMMARY, Event.ATTR_NONE, "Meet with customer");
}
if (event.isSupportedField(Event.LOCATION)) {
event.addString(Event.LOCATION, Event.ATTR_NONE, "Conference Center");
}
Date start = new Date(System.currentTimeMillis() + 8640000);
if (event.isSupportedField(Event.START)) {
event.addDate(Event.START, Event.ATTR_NONE, start);
}
if (event.isSupportedField(Event.END)) {
event.addDate(Event.END, Event.ATTR_NONE, start + 72000000);
}

37
BlackBerry Application Developer Guide

if (event.isSupportedField(Event.ALARM)) {
if (event.countValues(Event.ALARM) > 0) {
event.removeValue(Event.ALARM,0);
event.setInt(Event.ALARM, 0, Event.ATTR_NONE, 396000);
}
}

Create a recurring appointment

To define a recurrence pattern for an appointment, use a RepeatRule object. The RepeatRule class
defines fields for the properties and values that you can set, such as COUNT, FREQUENCY, and INTERVAL.
To retrieve an array of supported fields, invoke RepeatRule.getFields().

Define a recurrence pattern

Invoke setInt(int, int) or setDate(int, int, int, long) on a new RepeatRule object.
RepeatRule recurring = new RepeatRule();
recurring.setInt(RepeatRule.FREQUENCY, RepeatRule.MONTHLY);
recurring.setInt(RepeatRule.DAY_IN_MONTH, 14);

Assign a recurrence pattern to an appointment

Invoke setRepeat(RepeatRule) on an event.
EventList eventList = (EventList)PIM.getInstance().openPIMList(
PIM.EVENT_LIST, PIM.READ_WRITE);
Event event = eventList.createEvent();
event.setRepeat(recurring);

Modify appointment information

To replace an existing value with a new one, invoke the appropriate set method, such as setString().
To determine if a value is already set for the field, invoke countValues().
Note: If you invoke an add method, such as addString(), when a value already exists, a FieldFullException is thrown.
Use the corresponding set method, such as setString(), to change an existing value.
if (event.countValues(Event.LOCATION) > 0) {
event.setString(Event.LOCATION, 0, Event.ATTR_NONE, "Board Room");
}

Save an appointment
Tip: The importEvent() method saves the appointment, so you do not have to invoke commit().

Invoke commit(). Before you save the appointment, invoke isModified() to determine whether any of
the appointment fields have changed since the appointment was last saved.
if(event.isModified()) {
event.commit();
}

38
 3: Integrating PIM functions

Retrieving appointment information

Retrieve an enumeration of appointments
Invoke PIMList.items().
EventList eventList = (EventList)PIM.getInstance().openPIMList(
PIM.EVENT_LIST, PIM.READ_ONLY);
Enumeration e = eventList.items();

Retrieve field IDs and values

To retrieve an array of IDs of fields that have data for a particular task, invoke PIMItem.getFields().
To retrieve the field values, invoke PIMItem.getString().
while (e.hasMoreElements()) {
Event event = (Event)e.nextElement();
int[] fieldIds = event.getFields();
int id;
for(int index = 0; index < fieldIds.length; ++index) {
id = fieldIds[index];
if(e.getPIMList().getFieldDataType(id) == STRING) {
for(int j=0; j < event.countValues(id); ++j) {
String value = event.getString(id, j);
System.out.println(event.getFieldLable(id) + "=" + value);
}
}
}
}

Converting an appointment to a serial format

To import or export PIM item data, use an output stream writer to export tasks from the BlackBerry
device to a supported serial format, such as iCal.
To retrieve a string array of supported serial formats, invoke PIM.supportedSerialFormats(), and
then specify the list type (PIM.EVENT_List).

Write an item to a serial format

Invoke toSerialFormat().
EventList eventList = (EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST,
PIM.READ_ONLY );
ByteArrayOutputStream bytestream = new ByteArrayOutputStream();
Note: The enc parameter specifies the character encoding to use when writing to the output stream. Supported character
encodings include "UTF8," "ISO-8859-1," and "UTF-16BE". This parameter cannot be null.

Enumeration e = eventList.items();
while (e.hasMoreElements()) {
Event event = (Event)e.nextElement();
PIM.getInstance().toSerialFormat(event, byteStream, "UTF8", dataFormats[0]);
}

39
BlackBerry Application Developer Guide

Import an appointment
Invoke fromSerialFormat(java.io.InputStream is, java.lang.String enc), which returns an
array of PIMItem objects. Invoke EventList.importEvent() to add a new appointment.
Note: The enc parameter specifies the character encoding to use when writing to the output stream. Supported character
encodings include "UTF8," "ISO-8859-1," and "UTF-16BE." This parameter cannot be null.

// Convert an existing appointment into a iCal and then import the iCal as a new
// appointment.
String[] dataFormats = PIM.eventSerialFormats();
// Write appointment to iCal.
ByteArrayOutputStream os = new ByteArrayOutputStream();
PIM.getInstance().toSerialFormat(event, os, "UTF8", dataFormats[0]);
// Import appointment from iCal.
ByteArrayInputStream is = new ByteArrayInputStream(outputStream.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(is, "UTF8");
EventList eventList = (EventList)PIM.getInstance().openPIMList(
PIM.EVENT_LIST, PIM.READ_WRITE);
Event event2 = eventList.importEvent((Event)pi[0]);

Close an event list

Invoke close().
try {
eventList.close();
} catch (PimException e) {
// Handle exception.
}

Code example
The following example displays a screen that enables users to create new, recurring appointments in the
calendar. You could combine this sample with ContactsDemo.java to allow the user to invite attendees
to the meeting. See “ContactsDemo.java” on page 29 for more information.
After you save an appointment, click the Calendar icon to verify that the appointment was saved.

Example: EventDemo.java
/**
* EventDemo.java
* Copyright (C) 2002-2005 Research In Motion Limited.
*/

package com.rim.samples.docs.eventdemo;
import java.io.*;
import java.util.*;
import javax.microedition.pim.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.i18n.*;

40
 3: Integrating PIM functions

import net.rim.device.api.system.*;
import net.rim.device.api.util.*;
import com.rim.samples.docs.baseapp.*;

public final class EventDemo extends BaseApp {

private EventScreen _eventScreen;
public static void main(String[] args) {
new EventDemo().enterEventDispatcher();
}
private EventDemo() {
_eventScreen = new EventScreen();
pushScreen(_eventScreen);
}
protected void onExit() {
}
public final static class EventScreen extends MainScreen {
private EditField _subject, _location;
private SaveMenuItem _saveMenuItem;
private DateField _startTime, _endTime;
private ObjectChoiceField _repeat;
private Event event;
private class SaveMenuItem extends MenuItem {
public SaveMenuItem() {
super(null, 0, 100000, 5);
}
public String toString() {
return "Save";
}
public void run() {
onSave();
}
}
public EventScreen() {
_saveMenuItem = new SaveMenuItem();
setTitle(new LabelField("Event Demo", LabelField.ELLIPSIS |
LabelField.USE_ALL_WIDTH) );
_subject = new EditField("Subject: ", "");
add(_subject);
_location = new EditField("Location: ", "");
add(_location);
_startTime = new DateField("Start: ", System.currentTimeMillis() +
3600000, DateField.DATE_TIME);
_endTime = new DateField("End: ", System.currentTimeMillis() +
7200000, DateField.DATE_TIME);
add(new SeparatorField());
add(_startTime);
add(_endTime);
add(new SeparatorField());
String[] choices = {"None", "Daily", "Weekly", "Monthly", "Yearly"};
_repeat = new ObjectChoiceField("Recurrence: ", choices, 0);
add(_repeat);
}
protected boolean onSave() {
try {
EventList eventList = (EventList)PIM.getInstance().

41
BlackBerry Application Developer Guide

openPIMList(PIM.EVENT_LIST, PIM.WRITE_ONLY);
event = eventList.createEvent();
event.addString(Event.SUMMARY, PIMItem.ATTR_NONE,
_subject.getText());
event.addString(Event.LOCATION, PIMItem.ATTR_NONE,
_location.getText());
event.addDate(Event.END, PIMItem.ATTR_NONE, _endTime.getDate());
event.addDate(Event.START, PIMItem.ATTR_NONE,
_startTime.getDate());
if(_repeat.getSelectedIndex() != 0) {
event.setRepeat(setRule());
}
// Save the appointment to the Calendar.
event.commit();
//reset fields on screen
_subject.setText("");
_location.setText("");
_endTime.setDate(null);
_startTime.setDate(null);
_repeat.setSelectedIndex(0);
return true;
} catch (PIMException e) {
System.err.println(e);
}
return false;
}
private RepeatRule setRule() {
RepeatRule rule = new RepeatRule();
int index = _repeat.getSelectedIndex();
if (index == 0) {
rule.setInt(RepeatRule.FREQUENCY, RepeatRule.DAILY);
}
if (index == 1) {
rule.setInt(RepeatRule.FREQUENCY, RepeatRule.WEEKLY);
}
if (index == 2) {
rule.setInt(RepeatRule.FREQUENCY, RepeatRule.MONTHLY);
}
if (index == 3) {
rule.setInt(RepeatRule.FREQUENCY, RepeatRule.YEARLY);
}
return rule;
}
protected void makeMenu(Menu menu, int instance) {
menu.add(_saveMenuItem);
menu.addSeparator();
super.makeMenu(menu, instance);
}
}
}

42
 4
Adding handheld options
• Options API
• Adding option items

Options API
The BlackBerry options API, in the net.rim.blackberry.api.options package, enables you to add
items to the handheld options. Use this capability to add system-wide options to the BlackBerry device
that multiple applications can use.
When users click the Options icon on the Home screen, a list of options, such as AutoText, Date/Time,
and Firewall, appears. The user can select one of these items to view a screen for that particular option.
The screen displays one or more fields. Typically, the user can change the value of each field.

Adding option items

Register to add options
Your implementation of the OptionsProvider interface enables your application to add options items.
It includes implementations of getTitle(), save(), and populateMainScreen().

Adding option items when the BlackBerry device

starts
Create a library project with a libMain() method to perform the required registration.

Create a library project

1. In the IDE, create a project.
2. Right-click the project, and then click Properties.
3. In the Properties window, click the Application tab.
4. In the Project type drop-down list, click Library.
5. Select the Auto-run on startup option.
6. Click OK.

Register as an options provider

Your implementation of getInstance() retrieves a static instance of your class. Only one instance
should exist at a time.
Invoke registerOptionsProvider() in libMain(). Provide as a parameter a static instance of your
class.
BlackBerry Application Developer Guide

private static DemoOptionsProvider _instance;

//...
public static DemoOptionsProvider getInstance() {
if(_instance == null) {
_instance = new DemoOptionsProvider("Options Demo");
}
return _instance;
}
//...
public static void libMain(String[] args) {
OptionsManager.registerOptionsProvider(getInstance());
}

Store options
To store the option value that is currently selected, implement the Persistable interface. In your
implementation, define methods for setting the selected option value, and for committing and retrieving
an option value in the persistent store.
Note: If you implement the Persistable interface as an inner class, make it—and its get(), set(), and commit()
methods—public so that other applications can access your options data.

See “Managing persistent data” on page 85 for more information on storing persistent data.

Provide access to option data

In your library class, add public methods to enable other applications to access your option data.

Code example
This example demonstrates the use of the options facilities.

Example: DemoOptionsProvider.java
/**
* DemoOptionsProvider.java
* Copyright 2002-2005 Research In Motion Limited.
*/

package com.rim.samples.docs.demooptionsprovider;
import net.rim.blackberry.api.options.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.i18n.*;
import net.rim.device.api.system.*;
import net.rim.device.api.util.*;

// A simple library class to demonstrate the use of the options facilities.

public final class DemoOptionsProvider implements OptionsProvider {
// members
private ObjectChoiceField _ocf;

44
 4: Adding handheld options

private OptionsDemoData _data;

private String _title;
private static DemoOptionsProvider _instance;
// constructors
private DemoOptionsProvider() {
}
private DemoOptionsProvider(String title) {
_title = title;
_data = OptionsDemoData.load();
}
// Only allow one instance of this class.
public static DemoOptionsProvider getInstance() {
if (_instance == null) {
_instance = new DemoOptionsProvider("Options Demo");
}
return _instance;
}
// On startup, create the instance and register it.
public static void libMain(String[] args) {
OptionsManager.registerOptionsProvider(getInstance());
}
// Get the title for the option item.
public String getTitle() {
return _title;
}
// Add fields to the screen.
public void populateMainScreen(MainScreen screen) {
int index = _data.getSelected();
String[] choices = {"High", "Low", "None"};
_ocf = new ObjectChoiceField("Security: ", choices, index);
screen.add(_ocf);
}
// Save the data.
public void save() {
_data.setSelected(_ocf.getSelectedIndex());
_data.commit();
}
// Retrieve the data. Used by other applications to access options data.
public OptionsDemoData getData() {
return _data;
}
// Inner class to store selected option values.
public static final class OptionsDemoData implements Persistable {
private static final long ID = 0x6af0b5eb44dc5164L;
private int _selectedOption;
private OptionsDemoData() {
}
public int getSelected() {
return _selectedOption;
}
public void setSelected(int index) {
_selectedOption = index;
}
public void commit() {
PersistentObject.commit(this);

45
BlackBerry Application Developer Guide

}
private static OptionsDemoData load() {
PersistentObject persist = PersistentStore.getPersistentObject(
OptionsDemoData.ID );
OptionsDemoData contents = (OptionsDemoData)persist.getContents();
synchronized( persist ) {
if( contents == null ) {
contents = new OptionsDemoData();
persist.setContents( contents );
persist.commit();
}
}
return contents;
}
}
}

46
 5
BlackBerry Browser
• Browser APIs
• Displaying web content in the browser
• Displaying web content in a browser field
• Supporting additional MIME types
• Registering as an HTTP filter

Browser APIs
API name and package Description
Browser application API This API enables applications to display web content, including supported image types, HTML and WML
(net.rim.blackberry.api.browser) pages, by invoking the BlackBerry Browser. It also enables applications to supply a referrer, HTTP headers
and post data in an HTTP request. See “Displaying web content in the browser” on page 47 for more
information.
Browser field API This API enables an application to retrieve web content for display in a browser field, which is included
(net.rim.blackberry.api.browser. in the application UI. This API also enables applications to configure the appearance of the browser field,
field) such as by eliminating the scroll bar or specifying displaying the browser field in only a portion of the
screen. See “Displaying web content in a browser field” on page 48 for more information.
Browser page API This API enables applications to add support for additional MIME types. By registering as rendering
(net.rim.blackberry.api.browser. provider for a MIME type when the BlackBerry device starts, all subsequent browser sessions will support
plugin) the additional MIME type. See “Supporting additional MIME types” on page 62 for more information.
HTTP Filter API This API enables applications to register with the browser as provider for one or more URLs. See
(net.rim.device.api.io.http) “Registering as an HTTP filter” on page 67 for more information.

Displaying web content in the browser

To display web content in the BlackBerry Browser, use the browser application API
(net.rim.blackberry.api.browser).

Retrieve a browser session

To retrieve the default BrowserSession object, invoke the static method
Browser.getDefaultSession(). This object gives you access to the running browser on the BlackBerry
device.
Note: Retrieving the default session overrides any open sessions on the BlackBerry device.

To retrieve a different session, invoke getSession(). This method retrieves a browser configuration
service record according to its unique ID (UID). See “Service book API” on page 107 for more
information.
BlackBerry Application Developer Guide

Request a web page

To request a web page, invoke BrowserSession.displayPage(). The example below uses the version
of displayPage() that accepts only a URL. To specify a referrer, HTTP headers, and post data, use the
version that accepts these additional parameters.

Code sample
The following excerpt from the Restaurants.java sample creates a menu item that displays a web page in
the browser.
private MenuItem browserItem = new
MenuItem(_resources.getString(MENUITEM_BROWSER), 110, 12) {
public void run() {
synchronized(store) {
String websiteUrl = websitefield.getText();
if (websiteUrl.length == 0) {
Dialog.alert(_resources.getString(ALERT_NO_WEBSITE));
} else {
BrowserSession visit = Browser.getDefaultSession();
visit.displayPage(websiteUrl);
}
}
}
};

Displaying web content in a browser field

To include a browser field within an application UI, use the browser field API
(net.rim.device.api.browser.field). The browser rendering library handles the rendering of web
content for the field and then returns a BrowserField—a field in which URL content is rendered—to
your application for display.
Note: The browser session that is used to open a browser field is independent of the default browser session on the
BlackBerry device. Any open browser sessions are unaffected.

The RenderingApplication interface defines the callback functionality a rendering session requires to
assist with handling URL resources. Your implementation of the RenderingApplication interface
displays web content in a browser field.

Create a separate thread for rendering

To prevent the application from hanging while the application retrieves and displays the browser field,
perform these actions on a separate thread.
class CreationThread extends Thread {
BrowserFieldHandlerApplication _callBackApplication;
BasicRenderingApplication _renderingApplication;
public CreationThread(BrowserFieldHandlerApplication callBackApplication) {
_callBackApplication = callBackApplication;
}
public void run() {

48
 5: BlackBerry Browser

_renderingApplication = new
BasicRenderingApplication(_callBackApplication);
BrowserField field =
_renderingApplication.getBrowserField("www.blackberry.com");
_callBackApplication.displayBrowserField(field);
}
}

Set rendering options

Override getRenderingOptions(). If you do not override this method, default rendering options are
used. See RenderingOptions in the API Reference for more information.

Handle events
Your implementation of eventOccurred() handles events, such as a URL request.
public Object eventOccurred(Event event) {
int eventId = event.getUID();
switch (eventId) {
case Event.EVENT_URL_REQUESTED : {
UrlRequestedEvent e = (UrlRequestedEvent) event;
// This is a regular request.
String absoluteUrl = e.getURL();
HttpConnection conn = null;
OutputStream out = null;
try {
conn = (HttpConnection) Connector.open(absoluteUrl);
FormData postData = e.getPostData();
if (postData == null) {
conn.setRequestMethod(HttpConnection.GET);
} else {
conn.setRequestMethod(HttpConnection.POST);
byte[] postBytes = postData.getBytes();
conn.setRequestProperty(
HttpProtocolConstants.HEADER_CONTENT_LENGTH,
String.valueOf(postBytes.length));
if (conn.getRequestProperty(
HttpProtocolConstants.HEADER_CONTENT_TYPE) == null) {
conn.setRequestProperty(
HttpProtocolConstants.HEADER_CONTENT_TYPE,
postData.getContentType());
}
out = conn.openOutputStream();
out.write(postBytes);
}
HttpHeaders requestHeaders = e.getHeaders();
if (requestHeaders != null) {
/* From
http://www.w3.org/Protocols/rfc2616/rfc2616-
sec15.html#sec15.1.3
...
Clients SHOULD NOT include a Referer header field in a

49
BlackBerry Application Developer Guide

(non-secure) HTTP request if the referring page was

transferred with a secure protocol.*/
String referer =
requestHeaders.getPropertyValue("referer");
boolean sendReferrer = true;
if (referer != null && referer.startsWith("https:") &&
!absoluteUrl.startsWith("https:")) {
sendReferrer = false;
}
int size = requestHeaders.size();
for (int i = 0; i < size; i++) {
String header = requestHeaders.getPropertyKey(i);
// Remove refer header if needed.
if ( !sendReferrer && header.equals("referer")) {
requestHeaders.removeProperty(i);
continue;
}
conn.setRequestProperty( header,
requestHeaders.getPropertyValue( i ) );
}
}
} catch (IOException e1) {
} finally {
if (out != null) {
try {
out.close();
} catch (IOException e2) {
}
}
}
BrowserField browserField = getBrowserField(conn, e);
_callbackApplication.displayBrowserField(browserField);
break;
}
case Event.EVENT_BROWSER_FIELD_CHANGED : {
// Browser field title might have changed. Update title.
break;
}
case Event.EVENT_REDIRECT : {
RedirectEvent e = (RedirectEvent) event;
switch (e.getType()) {
case RedirectEvent.TYPE_SINGLE_FRAME_REDIRECT :
// Show redirect message.
Application.getApplication().invokeAndWait(new Runnable() {
public void run() {
Status.show("");
}
});
break;
case RedirectEvent.TYPE_JAVASCRIPT :
case RedirectEvent.TYPE_META :
case RedirectEvent.TYPE_300_REDIRECT :
}
String absoluteUrl = e.getLocation();
HttpConnection conn = null;

50
 5: BlackBerry Browser

try {
conn = (HttpConnection) Connector.open(absoluteUrl);
} catch (IOException e1) {
}
BrowserField browserField = getBrowserField(conn,
e.getOriginalEvent());
_callbackApplication.displayBrowserField(browserField);
break;
}
case Event.EVENT_CLOSE :
// Close the appication.
break;
case Event.EVENT_SET_HEADER :// no cache support
case Event.EVENT_SET_HTTP_COOKIE : // no cookie support
case Event.EVENT_HISTORY : // no history support
case Event.EVENT_LOADING_IMAGES :// no progress bar is supported
case Event.EVENT_EXECUTING_SCRIPT : // no progress bar is supported
case Event.EVENT_FULL_WINDOW : // no full window support
case Event.EVENT_STOP : // no stop loading support
default :
}
return null;
}

Retrieve browser content for rendering

Your implementation of getBrowserField() retrieves the browser content for rendering. The
getBrowserField() method invokes RenderingSession.getBrowserField() to retrieve a browser
field; applications cannot instantiate BrowserField directly.
public BrowserField getBrowserField (String absoluteUrl) {
HttpConnection conn = null;
try {
conn = (HttpConnection) Connector.open(absoluteUrl);
// Set transcode to true.
conn.setRequestProperty( "x-rim-transcode-content", "*/*" );
} catch (IOException e1) {
}
return getBrowserField(conn, null);
}
private BrowserField getBrowserField(HttpConnection conn, Event e) {
BrowserField field = null;
try {
field = _renderingSession.getBrowserField(conn, this, e);
} catch (RenderingException re) {
return null;
}
// Add to the event queue a thread that invokes finishLoading().
Application.getApplication().invokeLater(new RenderingThread(field));
return field;
}

51
BlackBerry Application Developer Guide

Render the browser field

Invoke BrowserField.finishLoading(). In the following code sample,
BrowserField.getBrowserField() runs finishLoading() by adding a new rendering thread to the
application event queue.
Notes: HTML files display a blank field until you invoke BrowserField.finishLoading(). WML files and images might
load before this method is invoked.
Run finishLoading() run on a separate thread so that the UI does not lock.

class RenderingThread implements Runnable {

BrowserField _browserField;
RenderingThread(BrowserField field) {
_browserField = field;
}
public void run() {
try {
_browserField.finishLoading();
} catch (RenderingException e) {
// Handle exception.
}

}
}

Display the browser field

Your implementation of displayBrowserField() deletes the screen contents and then adds the
browser field to the screen.
public void displayBrowserField(BrowserField browserField) {
synchronized (Application.getEventLock()) {
_vfm.deleteAll();
_vfm.add(browserField);
}
}

Code example
The following example consists of three files: BasicRenderingApplication.java,
BrowserFieldHandlerApplication.java, and BrowserFieldSampleApp.java.

Example: Browser field sample

/**
* BasicRenderingApplication.java
* Copyright (C) 2002-2005 Research In Motion Limited.
*/

package com.rim.samples.docs.browser;

import java.io.IOException;
import java.io.OutputStream;

52
 5: BlackBerry Browser

import javax.microedition.io.Connector;
import javax.microedition.io.HttpConnection;
import net.rim.device.api.browser.field.*;
import net.rim.device.api.io.http.HttpHeaders;
import net.rim.device.api.io.http.HttpProtocolConstants;
import net.rim.device.api.system.Application;
import net.rim.device.api.ui.Graphics;
import net.rim.device.api.ui.component.Status;
import com.rim.samples.docs.browser.BrowserFieldHandlerApplication.*;

final public class BasicRenderingApplication implements RenderingApplication {

RenderingSession _renderingSession;
BrowserFieldHandlerApplication _callbackApplication;
public BasicRenderingApplication(BrowserFieldHandlerApplication
callBackApplication) {
_renderingSession = RenderingSession.getNewInstance();
_callbackApplication = callBackApplication;
}
/**
* Simple method to get a browser field by specifying the URL.
* This call blocks until the browser field is returned by
RenderingSession.getBrowserField().
* The browser field can continue to be rendered after the field is returned.
*
* @param absoluteUrl - absolute url of the page to render
* @return rendered browser field
*/
public BrowserContent getBrowserField (String absoluteUrl) {
HttpConnection conn = null;
try {
conn = (HttpConnection) Connector.open(absoluteUrl);
// Set transcode to true.
conn.setRequestProperty( "x-rim-transcode-content", "*/*" );
} catch (IOException e1) {
}
return getBrowserField(conn, null);
}
private BrowserContent getBrowserField(HttpConnection conn, Event e) {
BrowserContent field = null;
try {
field = _renderingSession.getBrowserContent(conn, this, e);
} catch (RenderingException re) {
return null;
}
Application.getApplication().invokeLater(new RenderingThread(field));
return field;
}

/**
* Invoked when an event occurs.
*/
public Object eventOccurred(Event event) {
int eventId = event.getUID();
switch (eventId) {
case Event.EVENT_URL_REQUESTED : {
UrlRequestedEvent e = (UrlRequestedEvent) event;

53
BlackBerry Application Developer Guide

// this is a regular request

String absoluteUrl = e.getURL();
HttpConnection conn = null;
OutputStream out = null;
try {
conn = (HttpConnection) Connector.open(absoluteUrl);
byte[] postData = e.getPostData();
if (postData == null) {
conn.setRequestMethod(HttpConnection.GET);
} else {
conn.setRequestMethod(HttpConnection.POST);
conn.setRequestProperty(
HttpProtocolConstants.HEADER_CONTENT_LENGTH,
String.valueOf(postData.length));
out = conn.openOutputStream();
out.write(postData);
}
HttpHeaders requestHeaders = e.getHeaders();
if (requestHeaders != null) {
/* From
http://www.w3.org/Protocols/rfc2616/rfc2616-
sec15.html#sec15.1.3
...
Clients SHOULD NOT include a Referer header field in a
(non-secure) HTTP request if the referring page was
transferred with a secure protocol.*/
String referer = requestHeaders.getPropertyValue("referer");
boolean sendReferrer = true;
if (referer != null && referer.startsWith("https:") &&
!absoluteUrl.startsWith("https:")) {
sendReferrer = false;
}
int size = requestHeaders.size();
for (int i = 0; i < size; i++) {
String header = requestHeaders.getPropertyKey(i);
// Remove refer header if needed.
if ( !sendReferrer && header.equals("referrer")) {
requestHeaders.removeProperty(i);
continue;
}
conn.setRequestProperty( header,
requestHeaders.getPropertyValue( i ) );
}
}
} catch (IOException e1) {
} finally {
if (out != null) {
try {
out.close();
} catch (IOException e2) {
}
}
}
BrowserContent browserField = getBrowserField(conn, e);
_callbackApplication.displayBrowserField(browserField);
break;

54
 5: BlackBerry Browser

}
case Event.EVENT_BROWSER_CONTENT_CHANGED : {
// Browser field title might have changed. Update title.
break;
}
case Event.EVENT_REDIRECT : {
RedirectEvent e = (RedirectEvent) event;
switch (e.getType()) {
case RedirectEvent.TYPE_SINGLE_FRAME_REDIRECT :
// Show redirect message.
Application.getApplication().invokeAndWait(new Runnable() {
public void run() {
Status.show("");
}
});
break;
case RedirectEvent.TYPE_JAVASCRIPT :
case RedirectEvent.TYPE_META :
case RedirectEvent.TYPE_300_REDIRECT :
}
String absoluteUrl = e.getLocation();
HttpConnection conn = null;
try {
conn = (HttpConnection) Connector.open(absoluteUrl);
} catch (IOException e1) {
}
BrowserContent browserField = getBrowserField(conn,
e.getOriginalEvent());
_callbackApplication.displayBrowserField(browserField);
break;
}
case Event.EVENT_CLOSE :
// Close the appication.
break;

case Event.EVENT_TICK_CONTENT_READ : // No progress bar is supported.

case Event.EVENT_SET_HEADER : // No cache support.
case Event.EVENT_SET_HTTP_COOKIE : // No cookie support.
case Event.EVENT_HISTORY : // No history support.
case Event.EVENT_LOADING_IMAGES : // No progress bar is supported.
case Event.EVENT_EXECUTING_SCRIPT : // No progress bar is supported.
case Event.EVENT_FULL_WINDOW : // No full window support.
case Event.EVENT_STOP : // No stop loading support.
default :
}
return null;
}
/**
* Retrieves the pixels of height available for provided browser content.
* @param browserField Content for which to retrieve available pixels of
height.
* @return Height available.
*/
public int getAvailableHeight(BrowserContent browserField) {
// Field has full screen.
return Graphics.getScreenHeight();

55
BlackBerry Application Developer Guide

}
/**
* Retrieves the pixels of width available for provided browser content.
*/
public int getAvailableWidth(BrowserContent browserField) {
// Field has full screen.
return Graphics.getScreenWidth();
}
/**
* Retrieves the history position for provided browser content.
*/
public int getHistoryPosition(BrowserContent browserField) {
// No history support.
return 0;
}
/**
* Retrieves cookies associated with a provided URL.
*/
public String getHTTPCookie(String url) {
// No cookie support.
return null;
}
/**
* Retrieves the specified resource.
*/
public HttpConnection getResource( RequestedResource resource, BrowserContent
referrer) {
if (resource == null) {
return null;
}
// Check if this is cache-only request.
if (resource.isCacheOnly()) {
// No cache support.
return null;
}
String url = resource.getUrl();
if (url == null) {
return null;
}
// If referrer is null, return the connection.
if (referrer == null) {
HttpConnection conn;
try {
return (HttpConnection) Connector.open(resource.getUrl());
} catch (IOException e) {
return null;
}
} else {
// If referrer is provided, set up the connection on a
// separate thread.
Application.getApplication().invokeLater(
new RetrieveThread(resource, referrer));
}
return null;
}

56
 5: BlackBerry Browser

/**
* Invokes the provided runnable object.
*/
public void invokeRunnable(Runnable runnable) {
(new Thread(runnable)).run();
}
}
class RenderingThread implements Runnable {
BrowserContent _browserField;
RenderingThread(BrowserContent field) {
_browserField = field;
}
public void run() {
try {
_browserField.finishLoading();
} catch (RenderingException e) {
}
}
}

class RetrieveThread implements Runnable {

BrowserContent _browserField;
RequestedResource _resource;
RetrieveThread(RequestedResource resource, BrowserContent referrer) {
_browserField = referrer;
_resource = resource;
}
public void run() {
HttpConnection conn;
try {
conn = (HttpConnection) Connector.open(_resource.getUrl());
} catch (IOException e) {
return;
}
_resource.setHttpConnection(conn);
_browserField.resourceReady(_resource);
}
}
/**
* BasicRenderingApplication.java
* Copyright (C) 2002-2005 Research In Motion Limited.
*/

package com.rim.samples.docs.browser;

import java.io.IOException;
import java.io.OutputStream;
import javax.microedition.io.Connector;
import javax.microedition.io.HttpConnection;
import net.rim.device.api.browser.field.*;
import net.rim.device.api.io.http.HttpHeaders;
import net.rim.device.api.io.http.HttpProtocolConstants;
import net.rim.device.api.system.Application;
import net.rim.device.api.ui.Graphics;
import net.rim.device.api.ui.component.Status;

57
BlackBerry Application Developer Guide

import com.rim.samples.docs.browser.BrowserFieldHandlerApplication.*;

final public class BasicRenderingApplication implements RenderingApplication {

RenderingSession _renderingSession;
BrowserFieldHandlerApplication _callbackApplication;
public BasicRenderingApplication(BrowserFieldHandlerApplication
callBackApplication) {
_renderingSession = RenderingSession.getNewInstance();
_callbackApplication = callBackApplication;
}
/**
* Simple method to get a browser field by specifying the URL.
* This call blocks until the browser field is returned by
RenderingSession.getBrowserField().
* The browser field can continue to be rendered after the field is returned.
*
* @param absoluteUrl - absolute url of the page to render
* @return rendered browser field
*/
public BrowserContent getBrowserField (String absoluteUrl) {
HttpConnection conn = null;
try {
conn = (HttpConnection) Connector.open(absoluteUrl);
// Set transcode to true.
conn.setRequestProperty( "x-rim-transcode-content", "*/*" );
} catch (IOException e1) {
}
return getBrowserField(conn, null);
}
private BrowserContent getBrowserField(HttpConnection conn, Event e) {
BrowserContent field = null;
try {
field = _renderingSession.getBrowserContent(conn, this, e);
} catch (RenderingException re) {
return null;
}
Application.getApplication().invokeLater(new RenderingThread(field));
return field;
}

/**
* Invoked when an event occurs.
*/
public Object eventOccurred(Event event) {
int eventId = event.getUID();
switch (eventId) {
case Event.EVENT_URL_REQUESTED : {
UrlRequestedEvent e = (UrlRequestedEvent) event;
// this is a regular request
String absoluteUrl = e.getURL();
HttpConnection conn = null;
OutputStream out = null;
try {
conn = (HttpConnection) Connector.open(absoluteUrl);
byte[] postData = e.getPostData();
if (postData == null) {

58
 5: BlackBerry Browser

conn.setRequestMethod(HttpConnection.GET);
} else {
conn.setRequestMethod(HttpConnection.POST);
conn.setRequestProperty(
HttpProtocolConstants.HEADER_CONTENT_LENGTH,
String.valueOf(postData.length));
out = conn.openOutputStream();
out.write(postData);
}
HttpHeaders requestHeaders = e.getHeaders();
if (requestHeaders != null) {
/* From
http://www.w3.org/Protocols/rfc2616/rfc2616-
sec15.html#sec15.1.3
...
Clients SHOULD NOT include a Referer header field in a
(non-secure) HTTP request if the referring page was
transferred with a secure protocol.*/
String referer = requestHeaders.getPropertyValue("referer");
boolean sendReferrer = true;
if (referer != null && referer.startsWith("https:") &&
!absoluteUrl.startsWith("https:")) {
sendReferrer = false;
}
int size = requestHeaders.size();
for (int i = 0; i < size; i++) {
String header = requestHeaders.getPropertyKey(i);
// Remove refer header if needed.
if ( !sendReferrer && header.equals("referrer")) {
requestHeaders.removeProperty(i);
continue;
}
conn.setRequestProperty( header,
requestHeaders.getPropertyValue( i ) );
}
}
} catch (IOException e1) {
} finally {
if (out != null) {
try {
out.close();
} catch (IOException e2) {
}
}
}
BrowserContent browserField = getBrowserField(conn, e);
_callbackApplication.displayBrowserField(browserField);
break;
}
case Event.EVENT_BROWSER_CONTENT_CHANGED : {
// Browser field title might have changed. Update title.
break;
}
case Event.EVENT_REDIRECT : {
RedirectEvent e = (RedirectEvent) event;
switch (e.getType()) {

59
BlackBerry Application Developer Guide

case RedirectEvent.TYPE_SINGLE_FRAME_REDIRECT :
// Show redirect message.
Application.getApplication().invokeAndWait(new Runnable() {
public void run() {
Status.show("");
}
});
break;
case RedirectEvent.TYPE_JAVASCRIPT :
case RedirectEvent.TYPE_META :
case RedirectEvent.TYPE_300_REDIRECT :
}
String absoluteUrl = e.getLocation();
HttpConnection conn = null;
try {
conn = (HttpConnection) Connector.open(absoluteUrl);
} catch (IOException e1) {
}
BrowserContent browserField = getBrowserField(conn,
e.getOriginalEvent());
_callbackApplication.displayBrowserField(browserField);
break;
}
case Event.EVENT_CLOSE :
// Close the appication.
break;

case Event.EVENT_TICK_CONTENT_READ : // No progress bar is supported.

case Event.EVENT_SET_HEADER : // No cache support.
case Event.EVENT_SET_HTTP_COOKIE : // No cookie support.
case Event.EVENT_HISTORY : // No history support.
case Event.EVENT_LOADING_IMAGES : // No progress bar is supported.
case Event.EVENT_EXECUTING_SCRIPT : // No progress bar is supported.
case Event.EVENT_FULL_WINDOW : // No full window support.
case Event.EVENT_STOP : // No stop loading support.
default :
}
return null;
}
/**
* Retrieves the pixels of height available for provided browser content.
* @param browserField Content for which to retrieve available pixels of
height.
* @return Height available.
*/
public int getAvailableHeight(BrowserContent browserField) {
// Field has full screen.
return Graphics.getScreenHeight();
}
/**
* Retrieves the pixels of width available for provided browser content.
*/
public int getAvailableWidth(BrowserContent browserField) {
// Field has full screen.
return Graphics.getScreenWidth();
}

60
 5: BlackBerry Browser

/**
* Retrieves the history position for provided browser content.
*/
public int getHistoryPosition(BrowserContent browserField) {
// No history support.
return 0;
}
/**
* Retrieves cookies associated with a provided URL.
*/
public String getHTTPCookie(String url) {
// No cookie support.
return null;
}
/**
* Retrieves the specified resource.
*/
public HttpConnection getResource( RequestedResource resource, BrowserContent
referrer) {
if (resource == null) {
return null;
}
// Check if this is cache-only request.
if (resource.isCacheOnly()) {
// No cache support.
return null;
}
String url = resource.getUrl();
if (url == null) {
return null;
}
// If referrer is null, return the connection.
if (referrer == null) {
HttpConnection conn;
try {
return (HttpConnection) Connector.open(resource.getUrl());
} catch (IOException e) {
return null;
}
} else {
// If referrer is provided, set up the connection on a
// separate thread.
Application.getApplication().invokeLater(
new RetrieveThread(resource, referrer));
}
return null;
}

/**
* Invokes the provided runnable object.
*/
public void invokeRunnable(Runnable runnable) {
(new Thread(runnable)).run();
}
}
class RenderingThread implements Runnable {

61
BlackBerry Application Developer Guide

BrowserContent _browserField;
RenderingThread(BrowserContent field) {
_browserField = field;
}
public void run() {
try {
_browserField.finishLoading();
} catch (RenderingException e) {
}
}
}

class RetrieveThread implements Runnable {

BrowserContent _browserField;
RequestedResource _resource;
RetrieveThread(RequestedResource resource, BrowserContent referrer) {
_browserField = referrer;
_resource = resource;
}
public void run() {
HttpConnection conn;
try {
conn = (HttpConnection) Connector.open(_resource.getUrl());
} catch (IOException e) {
return;
}
_resource.setHttpConnection(conn);
_browserField.resourceReady(_resource);
}
}

Supporting additional MIME types

The browser page API, in the net.rim.device.api.browser.plugin package, enables third-party
applications to register themselves with the rendering library as rendering providers for specific MIME
types that are not currently supported by the BlackBerry Browser.
Note: The BrowserFieldProviderRegistry.register() method throws an exception if you try to register a MIME type
that is already supported by the BlackBerry Browser. For a list of supported MIME types, invoke
RenderingSession.getSupportedMimeType().

Register as rendering provider for a MIME type

To support additional MIME types, extend the BrowserContentProvider abstract class. To specify
display characteristics such as no scroll bar or full screen display, implement the BrowserPageContext
interface.
The rendering library invokes BrowserContentProvider.getAccept() and
BrowserContentProvider.getSupportedMimeTypes() to identify the MIME types the provider
renders.

62
 5: BlackBerry Browser

List accepted MIME types

Your implementation of getAccept() and getSupportedMimeTypes() lists the list of MIME types the
provider can accept given a set of rendering options. The getAccept() method considers the rendering
options that have been set; this example assumes that no rendering options are set. See
RenderingOptions in the API Reference for more information.
public String[] getAccept(RenderingOptions context) {
// Return subset of getSupportedMimeTypes() if accept depends on rendering
// options. For example, HTML can be disabled in the rendering options.
// This would cause HTMLConverter to remove HTML MIME types.
return ACCEPT;
}
public String[] getSupportedMimeTypes() {
return ACCEPT;
}

Specify display characteristics

Your implementation of the BrowserPageContext interface specifies display characteristics. If you do
not implement this interface, default values are used.
In this example, the properties are all integers. An application with Boolean, String, and Object
properties would implement the corresponding methods.
public boolean getPropertyWithBooleanValue(int id, boolean defaultValue) {
// TODO Implement.
return false;
}
public int getPropertyWithIntValue(int id, int defaultValue) {
if (id == BrowserPageContext.DISPLAY_STYLE) {
// Disable the scroll bar.
return BrowserPageContext.STYLE_NO_VERTICAL_SCROLLBAR;
}
return 0;
}
public Object getPropertyWithObjectValue(int id, Object defaultValue) {
// TODO Implement.
return null;
}
public String getPropertyWithStringValue(int id, String defaultValue) {
// TODO Implement.
return null;
}

Retrieve a field to render the content

Implement getBrowserContent(BrowserContentProviderContext).
public BrowserContent getBrowserContent( BrowserContentProviderContext context)
throws RenderingException {

if (context == null) {
throw new RenderingException("No Context is passed into Provider");
}

BrowserContentBaseImpl browserContentBaseImpl = new

BrowserContentBaseImpl(context.getHttpConnection().getURL(), null,

63
BlackBerry Application Developer Guide

context.getRenderingApplication(),
context.getRenderingSession().getRenderingOptions(), context.getFlags());
VerticalFieldManager vfm = new VerticalFieldManager(Manager.VERTICAL_SCROLL);
vfm.add(new LabelField("Mime type: ") );
vfm.add(new LabelField(ACCEPT[0]));
vfm.add(new SeparatorField());
vfm.add(new LabelField("Content of the resource file: \n"));
vfm.add(new SeparatorField());
try {
HttpConnection conn = context.getHttpConnection();
InputStream in = conn.openInputStream();
byte[] data = IOUtilities.streamToBytes(in);
vfm.add(new LabelField(new String(data)));

} catch (IOException e) {
// TODO Implement.
e.printStackTrace();
}
browserContentBaseImpl.setContent(vfm);
browserContentBaseImpl.setTitle(ACCEPT[0]);
// Set browser page context, this will tell the browser how to display this
// field.
browserContentBaseImpl.setBrowserPageContext(this);
return browserContentBaseImpl;
}

Register when the BlackBerry device starts

Create a library project and set its properties to auto-run on startup. In libMain(), invoke
BrowserFieldProviderRegistry.getInstance() and then invoke register().
public static void libMain( String[] args ) {
BrowserContentProviderRegistry converterRegistry =
BrowserContentProviderRegistry.getInstance();
if (converterRegistry != null) {
converterRegistry.register(new BrowserPlugin());
}
}

Code example
The following example consists of two files, LoaderApp.java, which adds support for the new MIME type
when the BlackBerry device starts, and BrowserPlugin.java, which contains a class that extends
BrowserContentProvider.

Example: BrowserPlugin.java and LoaderApp.java

/**
* LoaderApp.java
* Copyright (C) 2004-2005 Research In Motion Limited.
*/
package com.rim.samples.docs.browser;
import net.rim.device.api.browser.plugin.BrowserContentProviderRegistry;

64
 5: BlackBerry Browser

final class LoaderApp {

public static void libMain( String[] args ) {

BrowserContentProviderRegistry converterRegistry =
BrowserContentProviderRegistry.getInstance();
if (converterRegistry != null) {
converterRegistry.register(new BrowserPlugin());
}
}
}
/**
* BrowserPlugin.java
* Copyright (C) 2004-2005 Research In Motion Limited.
*/
package com.rim.samples.docs.browser;

import java.io.IOException;
import java.io.InputStream;

import javax.microedition.io.HttpConnection;

import net.rim.device.api.browser.field.*;
import net.rim.device.api.browser.plugin.*;
import net.rim.device.api.ui.Manager;
import net.rim.device.api.ui.component.LabelField;
import net.rim.device.api.ui.component.SeparatorField;
import net.rim.device.api.ui.container.VerticalFieldManager;

/**
* Create a file with xxtest extension and associate that type with
* application/x-vnd.rim.xxxtest mime type on any server.
*/
public final class BrowserPlugin extends BrowserContentProvider implements
BrowserPageContext {

private static final String[] ACCEPT = {"application/x-vnd.rim.xxxtest"};

/**
* Retrieves list of mime types this provider can accept given a set of rendering
options.
* @param context Rendering options in place this provider should consider.
* @return Array of mime types this provider will accept, given the provided
rendering options.
*/
public String[] getAccept(RenderingOptions context) {
// Return subset of getSupportedMimeTypes() if accept depends in rendering
options.
// For example HTML can be disabled in the rendering options, and
HTMLConverter would remove
// html MIME types.
return ACCEPT;
}
/**
* Retrieves a browser content capable of rendering the mime content this
provider can handle.
* @param context Provider context object provided by rendering session.

65
BlackBerry Application Developer Guide

* @return Browser content to render specialized content.

*/

public BrowserContent getBrowserContent( BrowserContentProviderContext context)

throws RenderingException {

if (context == null) {
throw new RenderingException("No Context is passed into Provider");
}

BrowserContentBaseImpl browserContentBaseImpl = new

BrowserContentBaseImpl(context.getHttpConnection().getURL(),
null, context.getRenderingApplication(),
context.getRenderingSession().getRenderingOptions(), context.getFlags());

VerticalFieldManager vfm = new

VerticalFieldManager(Manager.VERTICAL_SCROLL);

vfm.add(new LabelField("Mime type: ") );

vfm.add(new LabelField(ACCEPT[0]));
vfm.add(new SeparatorField());
vfm.add(new LabelField("Content of the resource file: \n"));
vfm.add(new SeparatorField());

try {
HttpConnection conn = context.getHttpConnection();
InputStream in = conn.openInputStream();
int numBytes = in.available();
byte[] data = new byte[numBytes];
in.read(data, 0, numBytes);
vfm.add(new LabelField(new String(data)));

} catch (IOException e) {
e.printStackTrace();
}
browserContentBaseImpl.setContent(vfm);
browserContentBaseImpl.setTitle(ACCEPT[0]);
// Set browser page context. This tells the browser how to display this
field.
browserContentBaseImpl.setBrowserPageContext(this);

return browserContentBaseImpl;
}
/**
* Retrieves all the mime content types supported by this provider.
* @return Mime types this converter supports.
*/

public String[] getSupportedMimeTypes() {

return ACCEPT;
}

/**
* Retrieves value of specified property as a boolean value.

66
 5: BlackBerry Browser

* @param id ID of property to query.

* @param defaultValue Expected default value of property.
* @return Current value of property.
*/

public boolean getPropertyWithBooleanValue(int id, boolean defaultValue) {

return false;
}
/**
* Retrieves value of specified property as an int.
* @param id ID of property to query.
* @param defaultValue Expected default value of property.
* @return Current value of property.
*/
public int getPropertyWithIntValue(int id, int defaultValue) {

if (id == BrowserPageContext.DISPLAY_STYLE) {
// Disable the scroll bar.
return BrowserPageContext.STYLE_NO_VERTICAL_SCROLLBAR;
}

return 0;
}
/**
* Retrieves value of specified property as an object.
* @param id ID of property to query.
* @param defaultValue Expected default value of property.
* @return Current value of property.
*/

public Object getPropertyWithObjectValue(int id, Object defaultValue) {

return null;
}
/* Retrieves value of specified property as a String value.
* @param id - ID of property to query.
* @param defaultValue - Expected default value of property.
* @return Current value of property.
*/
public String getPropertyWithStringValue(int id, String defaultValue) {
return null;
}
}

Registering as an HTTP filter

The HTTP filter API (net.rim.device.api.io.http) enables an application to register with the
browser as provider for a specific URL. When users type in the specified URL, the connection stack is
rerouted to the specified application.
Note: Check for a NoClassDefFoundError when your application first accesses the HTTP filter API. This error is thrown if
the system administrator restricts access to the HTTP filter API using application control. See BlackBerry Application
Developer Guide Volume 1: Fundamentals for more information.

67
BlackBerry Application Developer Guide

Register as an HTTP filter

Invoke HttpFilterRegistry.registerFilter(). Provide as parameters the URL to intercept and the
package name of the application that defines interception behaviour.
HttpFilterRegistry.registerFilter("content.blackberry.com",
"com.rim.samples.device.httpfilterdemo.precanned");

Perform registration at startup

Create a library project, and then set its properties to auto-run on startup. Invoke registerFilter() in
libMain().

Code example
The following example consists of two files, PackageManager.java, which registers the filter on startup,
and Protocol.java, which defines the filter behavior.

Example: HTTP filter example

/**
* PackageManager.java
* Copyright (C) 2004-2005 Research In Motion Limited. All rights reserved.
*/
package com.rim.samples.docs.httpfilterdemo;

import net.rim.device.api.io.http.HttpFilterRegistry;

/**
* This class runs on startup of the device and registers the necessary http
filters.
*/
final class PackageManager
{
public static void libMain(String[] args) {
HttpFilterRegistry.registerFilter("www.blackberry.com",
"com.rim.samples.docs.httpfilterdemo.filter");
}
}
/**
* Protocol.java
* Copyright (C) 2004 Research In Motion Limited. All rights reserved.
*/
package com.rim.samples.docs.httpfilterdemo.filter;

import net.rim.device.api.io.FilterBaseInterface;
import java.io.*;
import javax.microedition.io.*;

/**
* This class implements a simple pass through mechanism that writes out the http
response headers to System.out.
*/

68
 5: BlackBerry Browser

public final class Protocol implements FilterBaseInterface, HttpConnection {

private HttpConnection _subConnection;

/**
* Defined by FilterBaseInterface.
* This method opens a filtered Http Connection.
*/
public Connection openFilter( String name, int mode, boolean timeouts ) throws
IOException {
_subConnection = (HttpConnection)Connector.open("http:" + name +
";usefilter=false", mode, timeouts);
if (_subConnection != null) {
return this;
}

// Filed to open the sub connection; so let us fail too.

return null;
}

// Return a string representation of the URL for this connection.

public String getURL() {
return _subConnection.getURL();
}

// Returns the protocol name of the URL of this HttpConnection. e.g., http or
https.
public String getProtocol() {
return _subConnection.getProtocol();
}

// Returns the host information of the URL of this HttpConnection. e.g. host
name or IPv4 address.
public String getHost() {
return _subConnection.getHost();
}

// Returns the file portion of the URL of this HttpConnection.

public String getFile() {
return _subConnection.getFile();
}

/**
* Returns the ref portion of the URL of this HttpConnection.
* RFC2396 specifies the optional fragment identifier as the the text after the
crosshatch (#)
* character in the URL. This information may be used by the user agent as
additional
* reference information after the resource is successfully retrieved. The
format and
* interpretation of the fragment identifier is dependent on the media
type[RFC2046] of
* the retrieved information.
*/
public String getRef() {
return _subConnection.getRef();
}

69
BlackBerry Application Developer Guide

// Returns the network port number of the URL for this HttpConnection.
public int getPort() {
return _subConnection.getPort();
}

// Returns the query portion of the URL of this HttpConnection.

// RFC2396 defines the query component as the text after the first
// question-mark (?) character in the URL.
public String getQuery() {
return _subConnection.getQuery();
}

// Get the current request method. e.g. HEAD, GET, POST The default value is
GET.
public String getRequestMethod() {
return _subConnection.getRequestMethod();
}

// Set the method for the URL request, one of: GET, POST, HEAD, subject to
protocol restrictions. The default method is GET.
public void setRequestMethod(String method) throws IOException {
_subConnection.setRequestMethod(method);
}

// Returns the value of the named general request property for this connection.
public String getRequestProperty(String key) {
return _subConnection.getRequestProperty(key);
}

// Sets the general request property. If a property with the key already
exists, overwrite its value with the new value.
// Note: HTTP requires all request properties which can legally have multiple
instances with the
// same key to use a comma-separated list syntax which enables multiple
properties to be appended into a single property.
public void setRequestProperty(String key, String value) throws IOException {
System.out.println("Request property <key, value>: " + key + ", " + value );
_subConnection.setRequestProperty(key, value);
}

// Returns the HTTP response status code.

public int getResponseCode() throws IOException {
return _subConnection.getResponseCode();
}

// Gets the HTTP response message, if any, returned along with the response
code from a server.
public String getResponseMessage() throws IOException {
return _subConnection.getResponseMessage();
}

// Returns the value of the expires header field.

public long getExpiration() throws IOException {
return _subConnection.getExpiration();
}

70
 5: BlackBerry Browser

// Returns the value of the date header field.

public long getDate() throws IOException {
return _subConnection.getDate();
}

// Returns the value of the last-modified header field. The result is the
number of milliseconds since January 1, 1970 GMT.
public long getLastModified() throws IOException {
return _subConnection.getLastModified();
}

// Returns the value of the named header field.

public String getHeaderField(String name) throws IOException
{
String value = _subConnection.getHeaderField(name);
System.out.println("Response property <key, value>: " + name + ", " + value
);
return value;
}

// Returns the value of the named field parsed as a number.

public int getHeaderFieldInt(String name, int def) throws IOException {
return _subConnection.getHeaderFieldInt(name, def);
}

// Returns the value of the named field parsed as date. The result is the
// number of milliseconds since January 1, 1970 GMT represented by the named
field.
public long getHeaderFieldDate(String name, long def) throws IOException {
return _subConnection.getHeaderFieldDate(name, def);
}

// Gets a header field value by index.

public String getHeaderField(int n) throws IOException {
return _subConnection.getHeaderField(n);
}

// Gets a header field key by index.

public String getHeaderFieldKey(int n) throws IOException {
return _subConnection.getHeaderFieldKey(n);
}

// Returns the type of content that the resource connected to is providing.

public String getType() {
return _subConnection.getType();
}

// Returns a string describing the encoding of the content which the resource
connected to is providing.
public String getEncoding() {
return _subConnection.getEncoding();
}

// Returns the length of the content which is being provided.

71
BlackBerry Application Developer Guide

public long getLength() {

return _subConnection.getLength();
}

// Opens and returns an input stream for a connection.

public InputStream openInputStream() throws IOException {
return _subConnection.openInputStream();
}

// Opens and returns a data input stream for a connection.

public DataInputStream openDataInputStream() throws IOException {
return _subConnection.openDataInputStream();
}

// Opens and returns an output stream for a connection.

public OutputStream openOutputStream() throws IOException {
return _subConnection.openOutputStream();
}

// Opens and returns a data output stream for a connection.

public DataOutputStream openDataOutputStream() throws IOException {
return _subConnection.openDataOutputStream();
}

// Closes the connection.

public void close() throws IOException {
_subConnection.close();
}
}

72
 6
Accessing the phone
application
• Phone API
• Listening for phone events
• Accessing and managing phone logs

Phone API
The phone API (net.rim.blackberry.api.phone) provides access to advanced features of the phone
application, such as enabling applications to inject DTMF tones into active calls.
Notes: To simply invoke the phone application and place a phone call, use the invocation API
(net.rim.blackberry.api.invoke). See “Starting BlackBerry applications” on page 79 for more information.
Check for a ControlledAccessException when your application first accesses the phone API. This runtime exception is
thrown if the system administrator restricts access to the phone API using application control. See the BlackBerry
Application Developer Guide Volume 1: Fundamentals for more information.

Retrieve a phone call

To retrieve the active phone call, invoke Phone.getActiveCall(). To retrieve a phone call by call ID,
invoke Phone.getCall(int).
PhoneCall call = Phone.getActiveCall();

Retrieve phone call information

The PhoneCall class provides methods that enable applications to retrieve information about phone
calls. For example, the following code sample checks the length of the call, the status of the call, and
whether it is outgoing before displaying a message that includes the display phone number.
int threshold = 120; // Alert user if outgoing calls last longer than threshold.
int elapsedTime = call.getElapsedTime();
// Use getStatusString() to retrieve status as an string.
int status = call.getStatus();
if ((status == PhoneCall.STATUS_CONNECTED || status ==
PhoneCall.STATUS_CONNECTING) && call.isOutGoing() && elapsedTime > threshold) {
// Use getCallId() to retrieve the caller ID as as an integer.
String phoneNumber = call.getDisplayPhoneNumber();
Status.show("Your call to " + phoneNumber + " has lasted more than " +
(String)threshold + ".");
}
BlackBerry Application Developer Guide

Adding DTMF tones to the send queue

A Dual Tone Multi Frequency (DTMF, or touch-tone) tones consist of a low and high frequency that are
played at the same time.

Key Low Tone (Hz) High Tone (Hz)

1 697 1209
2 697 1336
3 697 1477
4 770 1209
5 770 1336
6 770 1477
7 852 1209
8 852 1336
9 852 1477
0 941 1209
* 941 1336
# 941 1477

Add a single DTMF tones to the send queue

Note: BlackBerry devices play DTMF tones as soon as no other tones are pending, overriding conversations.

Invoke sendDTMFTone().

Add multiple DTMF tones to the send queue

Invoke sendDTMFTones().

Retrieve the send queue for the current call

Invoke getDTMFTones().

Listening for phone events

Your implementation of the PhoneListener interface enables your application to listen for phone
events. Register your implementation with the system by invoking Phone.addPhoneListener().
To de-register a phone listener, invoke removePhoneListener().
To act on a particular event, implement one of the following methods.

Method Description
callAdded(int) This method is invoked when a call is added to a conference call.
callAnswered(int) This method is invoked when a user answers a call (user driven).
callConferenceCallEstablished(int) This method is invoked when a conference call is established.
callConnected(int) This method is invoked when the network indicates a connected event
(network driven).
callDirectConnectConnected(int) This method is invoked when a direct-connect call is connected.
callDirectConnectDisconnected(int) This method is invoked when a direct-connect call is disconnected.
callDisconnected(int) This method is invoked when a call is disconnected.
callEndedByUser(int) This method is invoked when a user ends the call.

74
 6: Accessing the phone application

Method Description
callFailed(int, int) This method is invoked when a call fails.
callHeld(int) This method is invoked when a call goes on hold.
callIncoming(int) This method is invoked when a new call arrives.
callInitiated(int) This method is invoked when an outgoing call is initiated by the BlackBerry
device.
callRemoved(int) This method is invoked when a call is removed from a conference call.
callResumed(int) This method is invoked when a held call resumes.
callWaiting(int) This method is invoked when a call is waiting.
conferenceCallDisconnected(int) This method is invoked when a conference call is ended (all members are
disconnected).

Accessing and managing phone logs

The phone logs API (net.rim.blackberry.api.phone.phonelogs) enables applications to access the
phone application log files. The phone call history consists of call logs, which represent individual phone
calls, grouped into a phone log.
Notes: Check for a NoClassDefFoundError when your application first accesses the phone logs API. This error is thrown
if the system administrator restricts access to the phone logs using application control. See the BlackBerry Application
Developer Guide Volume 1: Fundamentals for more information.

Retrieve phone logs

The PhoneLogs class represents the phone call history. It provides a method that enables you to open,
add, delete, or swap call logs.
To retrieve a phone log, invoke PhoneLogs.getInstance().
PhoneLogs _logs = PhoneLogs.getInstance();

Retrieve the number of calls in a folder

The phone logs are divided into two folders: FOLDER_NORMAL_CALLS and FOLDER_MISSED_CALLS. To
retrieve the number of calls in a folder, invoke numberOfCalls(int).
int numberOfCalls = _logs.numberOfCalls(FOLDER_NORMAL_CALLS);

Retrieve a call log

Invoke PhoneLogs.callAt(int).
You can instantiate two types of call logs: PhoneCallLog objects, which can only have one participant,
and ConferencePhoneCallLog objects, which have two or more participants. These objects enable you
to retrieve or change call log information, such as the participants or the date of the call.
PhoneCallLog phoneLog = (PhoneCallLog)_logs.callAt(0);

75
BlackBerry Application Developer Guide

Retrieve a call participant

The PhoneCallLogID class identifies participants in phone call log by phone number. Invoke
PhoneCallLog.getParticipant(int) or ConferencePhoneCallLog.getParticipantAt() to
retrieve a participant.
PhoneCallLogID participant = phoneLogs.getParticipant();

Create a call log or conference call log

Note: The PhoneCallLogID constructor strips dashes and other non-numeric characters from phone numbers.

Invoke the PhoneCallLog() or ConferencePhoneCallLog() constructor. Provide the date, duration,

participants, and notes for the call as parameters to the constructor.
Date date = new Date("1000"); // Date of call.
int duration = 60; // Duration of call.
PhoneCallLogID caller1 = new PhoneCallLogID("555-1234"); // First participant.
PhoneCallLogID caller2 = new PhoneCallLogID("555-1235"); // Second participant.
String notes = "New call."; // Notes.
ConferencePhoneCallLog conferenceCall = new ConferencePhoneCallLog(date, duration,
PhoneLogs.FOLDER_NORMAL_CALLS, caller1, caller2, notes);

Add the phone call to the phone log at the next available index
Invoke PhoneLogs.addCall().
_logs.addCall(conferenceCall);

Replace the call log at a given index with a new call log
Invoke PhoneLogs.swapCall().
_logs.swapCall(conferenceCall, 0, FOLDER_NORMAL_CALLS);

Note: The swapCall() method deletes the call at the given index.

Delete a call log

Invoke PhoneLogs.deleteCall().
_logs.deleteCall(0);

Code example
The following code example calculates the time spent on the phone with a given participant.

Example: PhoneLogsDemo.java
/**
* PhoneLogsDemo.java

76
 6: Accessing the phone application

* Copyright (C) 2001-2005 Research In Motion Limited. All rights reserved.

*/
package com.rim.samples.docs.phonelogs;

import net.rim.blackberry.api.phone.phonelogs.*;
import java.lang.*;
import com.rim.samples.docs.baseapp.*;
import net.rim.device.api.system.Application;

public class PhoneLogsDemo extends Application {

private PhoneLogs _logs;
private int _timeSpokenTo;
static public void main(String[] args) {
PhoneLogsDemo app = new PhoneLogsDemo();
app.enterEventDispatcher();
}
private PhoneLogsDemo() {
_logs = PhoneLogs.getInstance();
PhoneLogsDemo phoneLogsDemo = new PhoneLogsDemo();
PhoneCallLogID participant = new PhoneCallLogID("5551234");
_timeSpokenTo = phoneLogsDemo.findTimeSpokenTo(participant,
PhoneLogs.FOLDER_NORMAL_CALLS);
}

// Returns the number of seconds spent on the phone with a participant.

public int findTimeSpokenTo(PhoneCallLogID participant,
long folder) {
int numberOfCalls = this._logs.numberOfCalls(folder);
int timeSpokenTo = 0;
PhoneCallLog phoneCallLog;
ConferencePhoneCallLog conferencePhoneCallLog;
for (int i = 0; i < numberOfCalls; i++) {
Object o = _logs.callAt(i, folder);
if (o instanceof PhoneCallLog) {
phoneCallLog = (PhoneCallLog)_logs.callAt(i, folder);
if ( phoneCallLog.getParticipant() == participant)
timeSpokenTo += phoneCallLog.getDuration();
} else {
conferencePhoneCallLog = (ConferencePhoneCallLog)_logs.callAt(i,
folder);
int participants = conferencePhoneCallLog.numberOfParticipants();
for (int j = 0; j < participants; j++)
if (conferencePhoneCallLog.getParticipantAt(j) == participant) {
timeSpokenTo += conferencePhoneCallLog.getDuration();
j = participants;
}
}
}
return timeSpokenTo;
}
}

77
BlackBerry Application Developer Guide

78
 7
Communicating with
BlackBerry applications
• Starting BlackBerry applications
• Adding menu items to BlackBerry applications
• Code example

Starting BlackBerry applications

The invocation APIs (net.rim.blackberry.api.invoke) enable applications to start standard
BlackBerry applications.
Note: Check for a ControlledAccessException if your application invokes the phone. This runtime exception is thrown
if the system administrator restricts access to the phone application using application control. See the BlackBerry
Application Developer Guide Volume 1: Fundamentals for more information.
To start an application, call Invoke.invokeApplication(int, ApplicationArguments) with the
appropriate constant and an object of the appropriate ApplicationArguments subclass.
Note: Calling Invoke.invokeApplication(int, ApplicationArguments) results in a process context switch. When
the BlackBerry application is started, your application loses control. When the started application session ends, context
might not return to your application.

Application Constant Class

Address book APP_TYPE_ADDRESSBOOK AddressBookArguments
Calendar APP_TYPE_CALENDAR CalendarArguments
Memo pad APP_TYPE_MEMOPAD MemoArguments
Messages APP_TYPE_MESSAGES MessageArguments
Phone APP_TYPE_PHONE PhoneArguments
Tasks APP_TYPE_TASKS TaskArguments

Tips: The BlackBerry Browser is invoked from the browser application API (net.rim.blackberry.api.browser). See
"Displaying web content in the browser" on page 47 for more information.
The phone API (net.rim.blackberry.api.phone) provides access to advanced features of the phone application. See
"Phone API" on page 73 for more information.
The following excerpt from the Restaurants.java code example creates a menu item that invokes the
phone application to call a restaurant.
private MenuItem phoneItem = new MenuItem(_resources.getString(MENUITEM_PHONE),
110, 12) {
public void run() {
synchronized(store) {
String phoneNumber = phonefield.getText();
if ( phoneNumber.length == 0 ) {
Dialog.alert(_resources.getString(ALERT_NO_PHONENUMBER));
} else {
PhoneArguments call = new PhoneArguments(PhoneArguments.ARG_CALL,
phoneNumber);
BlackBerry Application Developer Guide

Invoke.invokeApplication(Invoke.APP_TYPE_PHONE, call);
}
}
}
};

Adding menu items to BlackBerry

applications
The application menu item API, in the net.rim.blackberry.api.menuitem package, enables you to
add menu items to BlackBerry applications.
For example, to integrate a customer relationship management application with the BlackBerry address
book application, add a View Sales Order menu item. When users click the View Sales Order menu item,
the application opens with a list of sales orders that the contact has placed.
The ApplicationMenuItemRepository class enables you to add or remove application menu items. It
provides constants that define the application contexts in which a menu item can appear. For example,
the ApplicationMenuItemRepository.MENUITEM_MESSAGE_LIST constant specifies that the menu item
appears when the messages screen is open.
The abstract ApplicationMenuItem class defines an item that appears in an application menu.

Create an application menu item

Extend the abstract ApplicationMenuItem class.
public class SampleMenuItem extends ApplicationMenuItem { ... }

Specify the position of the menu item in the menu

You can optionally override the constructor. In the following code sample, the constructor invokes
ApplicationMenuItem() with an integer that specifies the relative order of the item in the menu. (A
higher number means that the menu item appears lower in the menu.)
SampleMenuItem() {
super(20);
}

Specify the menu item text

Your implementation of toString() specifies the text that appears on the menu.
public String toString() {
return "Open the Contacts Demo application";
}

Specify menu item behavior

Your implementation of run() specifies the behavior of the menu item.
public Object run(Object context) {
Contact c = (Contact)context; // An error if this does not work.
if ( c ! null ) {

80
 7: Communicating with BlackBerry applications

new ContactsDemo().enterEventDispatcher();
} else {
throw new IllegalStateException( "Context is null, expected a Contact
instance");
}
Dialog.alert("Viewing a message in the messaging view");
return null;
}

Register the application menu item

Retrieve the application menu item repository
Invoke ApplicationMenuItemRepository.getInstance().
ApplicationMenuItemRepository repository =
ApplicationMenuItemRepository.getInstance();

Define a unique ID
Use the hash of the package name as the unique long ID for the application menu item repository.
long ID = 0x7cab1e23b72a0033L; // Hash of com.rim.samples.docs.menuitem.

Create your application menu item

Invoke the constructor.
TestApplicationMenuItem tami = new TestApplicationMenuItem();

Add the menu item to the repository

Invoke addMenuItem().
repository.addMenuItem(ApplicationMenuItemRepository.MENUITEM_ADDRESSCARD_VIEW,
tami);

Code example
The following code example creates a menu item that appears when a user views a contact in the
address book. When a user clicks the menu item, the Contacts Demo application appears.

Example: DemoAppMenuItem.java
/**
* DemoApplicationMenuItem.java
* Copyright (C) 2003-2005 Research In Motion Limited.
*/

package com.rim.samples.docs.menuitem;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.component.Dialog.*;
import net.rim.blackberry.api.menuitem.*;
import javax.microedition.pim.*;
import net.rim.device.api.pdap.*;

81
BlackBerry Application Developer Guide

import com.rim.samples.docs.contactsdemo.*;

public final class DemoAppMenuItem extends Application {

private static long ID = 0x7cab1e23b72a0033L;
//com.rim.samples.docs.menuitem

public static void main(String[] args) {

DemoAppMenuItem app = new DemoAppMenuItem();
app.enterEventDispatcher();
}

DemoAppMenuItem() {
ApplicationMenuItemRepository amir =
ApplicationMenuItemRepository.getInstance();
amir.addMenuItem(ApplicationMenuItemRepository.MENUITEM_ADDRESSCARD_VIEW,
new SampleMenuItem());
}

private static class SampleMenuItem extends ApplicationMenuItem {

SampleMenuItem() {
super(20);
}

public String toString() {

return "Open the Contacts Demo";
}

public Object run(Object context) {

BlackBerryContact c = (BlackBerryContact)context; //an error if this
doesn’t work
if ( c != null ) {
new ContactsDemo().enterEventDispatcher();
} else {
throw new IllegalStateException( "Context is null, expected a
Contact instance");
}
net.rim.device.api.ui.component.Dialog.alert("Viewing an email message
in the email view");
return null;
}
}
}

82
 8
Storing persistent data
• Persistent storage options
• Managing persistent data
• Memory management and persistent objects
• Managing custom objects

Persistent storage options

Store data on the BlackBerry device in one of the following ways:
• using Mobile Information Device Profile (MIDP) record stores
• using the BlackBerry persistence model
Use the MIDP implementation if you want your application to be portable across multiple devices that
are compatible with the Java™ 2 Platform, Micro Edition (J2ME). If you are writing an application
specifically for BlackBerry devices, use the BlackBerry persistence model because it provides a more
flexible and efficient way to store data.

MIDP record stores

The javax.microedition.rms package provides the MIDP record store implementation. Persistent
data is stored in RecordStore objects. A record store can be a maximum of 64 KB.
Discrete units of data are called records. A record is an array of bytes that is assigned a unique
identification number.

Create a record store

Invoke openRecordStore(). Specify true to indicate that the record store should be created if it does
not exist.
RecordStore store = RecordStore.openRecordStore("Contacts", true);
Notes: When an application is deleted from a BlackBerry device, all record stores created by that application are also
deleted.
Each record store has a unique name within a MIDlet suite. A MIDlet can only access record stores that are created by a
MIDlet in the same suite.

Add a record
Invoke addRecord().
int id = store.addRecord(_data.getBytes(), 0, data.length());

Retrieve a record
Invoke getRecord(int, byte[], int). Provide a record ID, a byte array, and an offset as parameters
to this method.
byte[] data = new byte[store.getRecordSize(id)];
BlackBerry Application Developer Guide

store.getRecord(id, data, 0);

String dataString = new String(data);

Retrieve all records

Open the record store and then retrieve the enumeration.
RecordStore store = RecordStore.openRecordStore("Contacts", false);
RecordEnumeration e = store.enumerateRecords(null, null, false);

The enumerateRecords(RecordFilter filter, RecordComparator comparator, Boolean

keepUpdated) method accepts the following parameters:

Parameter Description
filter This parameter specifies a RecordFilter object to retrieve a subset of record store records (if null, all
record store records are returned).
comparator This parameter specifies a RecordComparator object to determine the order in which records are
returned (if null, records are returned in an undefined order).
keepUpdated This parameter determines whether the enumeration is kept current with changes to the record store.

BlackBerry persistent storage

There are two main differences between the MIDP record store (RecordStore) and the BlackBerry
persistence model (PersistentStore).

Feature Description
Data storage MIDP records store data only as byte arrays. In contrast, the BlackBerry APIs enable you to save any Object
in the persistent store. As a result, searching for stored data is much faster than in the record model. To store
custom object types, the custom type’s class must implement the Persistable interface.
Data sharing In MIDP, each RecordStore belongs to a single MIDlet suite and a MIDlet can only access record stores
that are created by a MIDlet in the same suite. In the BlackBerry persistence model, however, data can be
shared between applications, at the discretion of the application that creates the data. Code signing ensures
that only authorized applications can access the data.

Note: The BlackBerry persistence API is available only with handheld software version 3.6 or later. For earlier versions of
handheld software, you must use MIDP record stores.

Conserving storage space

BlackBerry devices have limited storage space. You should design your application carefully to minimize
the amount of flash memory that is required to store persistent data.
On a typical BlackBerry device, the storage space not required for standard BlackBerry applications must
be shared between all applications to store user data, including calendar appointments, contacts, and
messages.
If the BlackBerry device is operating with low memory, it might perform the following actions to free
memory space:
• delete old messages from the BlackBerry device
• delete calendar appointments that are more than one week old from the BlackBerry device (if
wireless calendar synchronization is enabled)

84
 8: Storing persistent data

If the BlackBerry device deletes messages or calendar appointments because of low memory, the data is
not deleted from the desktop messaging program. See “Memory management and persistent objects” on
page 89 for more information.
Note: Users can view the current amount of available data storage by clicking Status in the handheld options.

Backup and restore

The synchronization API, in the net.rim.device.api.synchronization package, enables you to
back up and restore custom persistent data on the BlackBerry device. See "Adding support for backing
up persistent data" on page 98 for more information.

Security
By default, applications on the BlackBerry device that have been digitally signed by RIM can access your
data in the persistent store. Contact RIM for information on controlling access to your data.

Administrative control
With the BlackBerry Enterprise Server version 3.5 Service Pack 2 or later for Microsoft® Exchange or
BlackBerry Enterprise Server version 2.2 or later for IBM® Lotus® Domino®, system administrators can
use IT policies to control the use of persistent storage by third-party applications.
Administrators can set the application control item ALLOW_USE_PERSISTENT_STORE to TRUE or FALSE.
By default, third-party applications are allowed to use persistent storage
(ALLOW_USE_PERSISTENT_STORE is TRUE).
Note: This policy item does not affect the use of the MIDP record store.

Data integrity
To maintain the integrity of data in persistent storage, partial updates are not made if an error occurs
during a commit.
Note: Data integrity can be compromised when the VM performs an emergency garbage collection due to low memory. In
this case, outstanding transactions are committed immediately. If the BlackBerry device fails during this operation, the
partially completed transactions are committed when the BlackBerry device starts. Outstanding transactions are not
committed during normal garbage collection.

Managing persistent data

Persistent data types
A custom data type can be stored persistently if its class implements the Persistable interface.
The following native data types can also be stored persistently:
• java.lang.Boolean
• java.lang.Byte
• java.lang.Character
• java.lang.Integer
• java.lang.Long
• java.lang.Object

85
BlackBerry Application Developer Guide

• java.lang.Short
• java.lang.String
• java.util.Vector
• java.util.Hashtable
Note: When you persist an object, any persistable objects that it refers to are also persisted.

Create a persistent database

Each application typically creates a single PersistentObject. This object is the root database of
persistent data and indexes for the application. The application saves data into this PersistentObject.
Note: Use a static constructor so that the PersistentObject is created only once, the first time that an object of this
class is created. Each time a process starts, the static blocks that it contains are run again.

Each PersistentObject is identified by a unique long key. This key is typically a hash of the fully
qualified package name.
Note: When an application is deleted from a BlackBerry device, all persistent objects created by that application are also
deleted.

Create a unique long key

1. In the IDE, type a string value, such as com.rim.samples.docs.userinfo.
2. Select this string.
3. Right-click, and then click Convert 'com.rim.samples.docs.userinfo' to long. The long value appears.

Note: Include a comment in your code to indicate the string used to generate the long key.

static PersistentObject store;

static {
store = PersistentStore.getPersistentObject( 0xa1a569278238dad2L );
}

Store data persistently

To save data to the persistent store, invoke setContents() on a PersistentObject. This method
replaces existing content with the new content. Invoke commit() to save to the persistent store.
Note: If an error occurs during a commit, partial updates are not committed. Data in the PersistentObject retains the
values from the last commit in order to preserve data integrity.

String[] userinfo = {username, password};

synchronized(store) {
store.setContents(userinfo);
store.commit();
}

86
 8: Storing persistent data

If you have a number of objects that you want to commit to the store, you can commit them in a batch
transaction. To do this, invoke PersistentStore.getSynchObject() to retrieve the persistent store
monitor locking object. Then synchronize on that object, and invoke commit() as necessary. When you
release the synchronization on the monitor object, all your transactions are committed at once. If any
commit in the batch fails, then the entire batch transaction fails. If you invoke forceCommit() while
synchronized on the monitor object, this object is immediately committed and is not part of the batch
transaction.

Retrieve persistent data

Invoke getContents() on a PersistentObject.
Perform an explicit cast on the object that is returned by PersistentObject.getContents() to
convert it to your desired format.
synchronized(store) {
String[] currentinfo = (String[])store.getContents();
if(currentinfo == null) {
Dialog.alert(_resources.getString(APP_ERROR));
} else {
currentusernamefield.setText(currentinfo[0]);
currentpasswordfield.setText(currentinfo[1]);
}
}

Note: When an application first accesses a database, it should verify the order of any indexes and recreate the index if a
problem exists. Applications should also be able to identify and correct any problems with corrupt or missing data. See
"Data integrity" on page 85 for more information.

Delete a database
To delete a database, invoke PersistentStore.destroyPersistentObject(). Provide a unique key
for the PersistentObject as a parameter.
Notes: The PersistentObject is used as the root database for the application. By deleting it, you permanently remove
all persistent data that the application has stored.
If the .cod file that defines a PersistentStore is deleted, all persistent objects created by that .cod are also deleted.
To delete individual data, simply treat the data as normal objects and remove references to it. The data is
garbage collected automatically.

Code example
This code example demonstrates how to create an application for users to view their current user name
and password, type a new user name and password, and save changes.

Example: UserInfo.java
/**
* UserInfo.java
* Copyright (C) 2001-2005 Research In Motion Limited. All rights reserved.
*/

87
BlackBerry Application Developer Guide

package com.rim.samples.docs.userinfo;

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.system.*;
import net.rim.device.api.util.*;
import java.util.*;
import net.rim.device.api.i18n.*;
import com.rim.samples.docs.baseapp.*;
import com.rim.samples.docs.resource.*;

public class UserInfo extends BaseApp implements UserInfoResource,

KeyListener, TrackwheelListener {

private static PersistentObject store;

private static ResourceBundle _resources;
private AutoTextEditField usernamefield;
private PasswordEditField passwordfield;
private AutoTextEditField currentusernamefield;
private AutoTextEditField currentpasswordfield;

static {
_resources = ResourceBundle.getBundle(
UserInfoResource.BUNDLE_ID, UserInfoResource.BUNDLE_NAME);
store = PersistentStore.getPersistentObject(0xa1a569278238dad2L);
}

private MenuItem saveItem = new MenuItem( _resources.getString(MENUITEM_SAVE),

110, 10) {
public void run() {
String username = usernamefield.getText();
String password = passwordfield.getText();
String[] userinfo = {username, password};
synchronized(store) {
store.setContents(userinfo);
store.commit();
}

Dialog.inform(_resources.getString(APP_SUCCESS));

usernamefield.setText(null);
passwordfield.setText(null);
}
};

private MenuItem getItem = new MenuItem( _resources.getString(MENUITEM_GET),

110, 11 ) {
public void run() {
synchronized(store) {
String[] currentinfo = (String[])store.getContents();
if(currentinfo == null) {
Dialog.alert(_resources.getString(APP_ERROR));
} else {
currentusernamefield.setText(currentinfo[0]);
currentpasswordfield.setText(currentinfo[1]);

88
 8: Storing persistent data

}
}
}
};

public static void main(String[] args) {

UserInfo app = new UserInfo();
app.enterEventDispatcher();
}

public UserInfo() {
MainScreen mainScreen = new MainScreen();
mainScreen.setTitle(new LabelField(
_resources.getString(APPLICATION_TITLE)));

usernamefield = new AutoTextEditField(

_resources.getString(FIELD_NAME), "");
passwordfield = new PasswordEditField(
_resources.getString(FIELD_PASSWORD), "");
currentusernamefield = new AutoTextEditField(
_resources.getString(FIELD_CURRENTNAME), "");
currentpasswordfield = new AutoTextEditField(
_resources.getString(FIELD_CURRENTPASSWORD), "");

SeparatorField separator = new SeparatorField();

mainScreen.add(usernamefield);
mainScreen.add(passwordfield);
mainScreen.add(separator);
mainScreen.add(currentusernamefield);
mainScreen.add(currentpasswordfield);
mainScreen.addKeyListener(this);
mainScreen.addTrackwheelListener(this);
pushScreen(mainScreen);
}
public void makeMenu( Menu menu, int instance ) {
menu.add(saveItem);
menu.add(getItem);
super.makeMenu(menu, 0);
}
public void onExit() {
Dialog.alert(_resources.getString(APP_EXIT));
}
}

Memory management and persistent objects

There are a fixed number of persistent object handles and object handles on BlackBerry devices.

Flash memory Persistent object Handles Object handles

8 MB 12,000 24,000
16 MB 27,000 56,000

89
BlackBerry Application Developer Guide

Flash memory Persistent object Handles Object handles

32 MB 65,000 132,000

Each persistent object on the BlackBerry device consumes a persistent object handle and an object
handle. For example, a record that consists of 10 String fields consumes 11 object handles—one for the
record and one for each of the strings. If the record is persistent, it consumes an additional 11 persistent
object handles.
Use the following techniques to limit the number of persistent object handles your application
consumes:
• Use primitives instead of objects when possible. A primitive, such as an int or a char, does not
consume an object handle.
• Group objects using the Object Grouping API (net.rim.device.api.system.ObjectGroup). A
grouped object consumes only one object handle.
Notes: Grouped objects are read-only. Invoke ObjectGroup.expandGroup() to ungroup the objects before making
changes. After you have finished making changes, invoke ObjectGroup.createGroup() to group the objects.
Objects should only be ungrouped when necessary. There is a performance penalty applied when objects are
ungrouped because the system creates a copy of the grouped object and allocates handles to each of the objects
inside the group.
See the Memory Best Practices for the BlackBerry Java Development Environment whitepaper for more
information.

Managing custom objects

Create a database
Create a Vector object to store multiple objects. Create a PersistentObject as the root database of
your application.
private static Vector _data;
PersistentObject store;
static {
store = PersistentStore.getPersistentObject( 0xdec6a67096f833cL );
//key is hash of test.samples.restaurants
_data = (Vector)store.getContents();
synchronized (store) {
if (_data == null) {
_data = new Vector();
store.setContents(_data);
store.commit();
}
}
}

Store data persistently

Objects that implement the Persistable interface are persistent.

90
 8: Storing persistent data

The following code sample implements the Persistable interface as an inner class. It defines an
Object array with four elements to store a restaurant name, address, phone number, and specialty, and
methods to retrieve and set values for Object elements.
Note: A class must explicitly implement Persistable for objects of the class to be saved persistently. This requirement
applies even to subclasses. For example, if class A implements Persistable, and it has a subclass B, objects of subclass B
cannot be stored persistently unless class B also implements Persistable.

private static final class RestaurantInfo implements Persistable {

private String[] _elements;
public static final int NAME = 0;
public static final int ADDRESS = 1;
public static final int PHONE = 2;
public static final int SPECIALTY = 3;
public RestaurantInfo() {
_elements = new String[4];
for ( int i = 0; i < _elements.length; ++i) {
_elements[i] = new String("");
}
}
public String getElement(int id) {
return _elements[id];
}
public void setElement(int id, String value) {
_elements[id] = value;
}
}

Creating expandable objects

Use the following strategies to allow you to add fields to your objects:
• Store Boolean values as bits in an int. Reserve extra bits for future use.
• Store Strings directly, but use a vector or hashtable of key/value pairs so that additional (or
seldom-used) fields can be added.
• If you have indexes on a table, store them in a vector or array so that you can add further indexes.

Saving an object
Define an object
The following code sample creates a RestaurantInfo object and uses its set methods to define its
components.
RestaurantInfo info = new RestaurantInfo();
info.setElement(RestaurantInfo.NAME, namefield.getText());
info.setElement(RestaurantInfo.ADDRESS,addressfield.getText());
info.setElement(RestaurantInfo.PHONE, phonefield.getText());
info.setElement(RestaurantInfo.SPECIALTY, specialtyfield.getText());

Add the object to a vector

Invoke addElement().

91
BlackBerry Application Developer Guide

_data.addElement(info);

Save the updated data

Invoke setContents(), and then commit() on the PersistentObject to save the updated data.
synchronized(store) {
store.setContents(_data);
store.commit();
}

Note: Synchronize on the persistent object when you make changes so that other threads cannot make changes to the
object at the same time.

Retrieve an object
To retrieve the most recently saved object, invoke _data.lastElement() .
public void run() {
synchronized(store) {
_data = (Vector)store.getContents();
if (!_data.isEmpty()) { RestaurantInfo info =
(RestaurantInfo)_data.lastElement();
namefield.setText(info.getElement(RestaurantInfo.NAME));
addressfield.setText(info.getElement(RestaurantInfo.ADDRESS));
phonefield.setText(info.getElement(RestaurantInfo.PHONE));
specialtyfield.setText(info.getElement(
RestaurantInfo.SPECIALTY));
}
}
}

Code example
This code example demonstrates how to create an application that enables users to store information
about a favorite restaurant.
This code example enables users to save information about multiple restaurants and view information
about the most recently saved restaurant.

Example: Restaurants.java
/**
* Restaurants.java
* Copyright (C) 2004-2005 Research In Motion Limited.
*/

package com.rim.samples.docs.restaurants;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.system.*;
import net.rim.device.api.util.*;
import java.util.*;

92
 8: Storing persistent data

import net.rim.device.api.i18n.*;
import net.rim.blackberry.api.invoke.*;
import net.rim.blackberry.api.browser.*;
import com.rim.samples.docs.baseapp.*;
import com.rim.samples.docs.resource.*;

public class Restaurants extends BaseApp implements RestaurantResource,

KeyListener, TrackwheelListener {

private AutoTextEditField namefield;

private AutoTextEditField addressfield;
private EditField phonefield;
private EditField websitefield;
private EditField specialtyfield;

private static Vector _data;

private static PersistentObject store;
private static ResourceBundle _resources;

private MenuItem saveItem = new MenuItem(_resources.getString(MENUITEM_SAVE),

110, 10) {
public void run() {
RestaurantInfo info = new RestaurantInfo();

info.setElement(RestaurantInfo.NAME, namefield.getText());
info.setElement(RestaurantInfo.ADDRESS, addressfield.getText());
info.setElement(RestaurantInfo.PHONE, phonefield.getText());
info.setElement(RestaurantInfo.WEBSITE, phonefield.getText());
info.setElement(RestaurantInfo.SPECIALTY,
specialtyfield.getText());

_data.addElement(info);

synchronized(store) {
store.setContents(_data);
store.commit();
}
Dialog.inform(_resources.getString(APP_SUCCESS));
namefield.setText(null);
addressfield.setText(null);
phonefield.setText("");
websitefield.setText("");
specialtyfield.setText("");
}
};

private MenuItem getItem = new MenuItem(_resources.getString(MENUITEM_GET),

110, 11) {
public void run() {
synchronized(store) {
_data = (Vector)store.getContents();
if (!_data.isEmpty()) {
RestaurantInfo info = (RestaurantInfo)_data.lastElement();
namefield.setText(info.getElement(RestaurantInfo.NAME));
addressfield.setText(info.getElement(RestaurantInfo.ADDRESS));
phonefield.setText(info.getElement(RestaurantInfo.PHONE));

93
BlackBerry Application Developer Guide

websitefield.setText(info.getElement(RestaurantInfo.WEBSITE));

specialtyfield.setText(info.getElement(RestaurantInfo.SPECIALTY));
}
}
}
};

private MenuItem phoneItem = new MenuItem(_resources.getString(MENUITEM_PHONE),

110, 12) {
public void run() {
synchronized(store) {
String phoneNumber = phonefield.getText();
if ( phoneNumber.length() == 0) {
Dialog.alert(_resources.getString(ALERT_NO_PHONENUMBER));
} else {
PhoneArguments call = new
PhoneArguments(PhoneArguments.ARG_CALL, phoneNumber);
Invoke.invokeApplication(Invoke.APP_TYPE_PHONE, call);
}
}
}
};
private MenuItem browserItem = new
MenuItem(_resources.getString(MENUITEM_BROWSER), 110, 12) {
public void run() {
synchronized(store) {
String websiteUrl = websitefield.getText();
if (websiteUrl.length() == 0) {
Dialog.alert(_resources.getString(ALERT_NO_WEBSITE));
} else {
BrowserSession visit = Browser.getDefaultSession();
visit.displayPage(websiteUrl);
}
}
}
};
static {
_resources = ResourceBundle.getBundle(
RestaurantResource.BUNDLE_ID,
RestaurantResource.BUNDLE_NAME);
store = PersistentStore.getPersistentObject(0xdec6a67096f833cL);
// Key is hash of test.samples.restaurants.
synchronized (store) {
_data = (Vector)store.getContents();
if (_data == null) {
_data = new Vector();
store.setContents( _data );
store.commit();
}
}

public static void main(String[] args) {

Restaurants app = new Restaurants();

94
 8: Storing persistent data

app.enterEventDispatcher();
}
private static final class RestaurantInfo implements Persistable {

// Data.
private String[] _elements;

// Fields.
public static final int NAME = 0;
public static final int ADDRESS = 1;
public static final int PHONE = 2;
public static final int WEBSITE = 3;
public static final int SPECIALTY = 4;

public RestaurantInfo() {
_elements = new String[4];
for ( int i = 0; i < _elements.length; ++i) {
_elements[i] = new String("");
}
}

public String getElement(int id) {

return _elements[id];
}

public void setElement(int id, String value) {

_elements[id] = value;
}
}

public Restaurants() {
MainScreen mainScreen = new MainScreen();
mainScreen.setTitle(new LabelField(
_resources.getString(APPLICATION_TITLE)));
namefield = new AutoTextEditField(
_resources.getString(FIELD_NAME), "");
addressfield = new AutoTextEditField(
_resources.getString(FIELD_ADDRESS), "");
phonefield = new EditField(
_resources.getString(FIELD_PHONE), "", Integer.MAX_VALUE,
BasicEditField.FILTER_PHONE);
websitefield = new EditField(
_resources.getString(FIELD_WEBSITE), "", Integer.MAX_VALUE,
BasicEditField.FILTER_URL);
specialtyfield = new EditField(
_resources.getString(FIELD_SPECIALTY), "",
Integer.MAX_VALUE, BasicEditField.FILTER_DEFAULT);

mainScreen.add(namefield);
mainScreen.add(addressfield);
mainScreen.add(phonefield);
mainScreen.add(websitefield);
mainScreen.add(specialtyfield);
mainScreen.addKeyListener(this);
mainScreen.addTrackwheelListener(this);

95
BlackBerry Application Developer Guide

pushScreen(mainScreen);
}

public void makeMenu( Menu menu, int instance ) {

menu.add(saveItem);
menu.add(getItem);
menu.add(phoneItem);
menu.add(browserItem);
super.makeMenu(menu, instance);
}

public void onExit() {

Dialog.alert(_resources.getString(APP_EXIT));
}
}

96
 9
Backing up and restoring
persistent data
• Synchronization API
• Adding support for backing up persistent data

Synchronization API
The synchronization API, in the net.rim.device.api.synchronization package, enables your
application to integrate with the BlackBerry Desktop Software to perform two tasks:
• back up a database to a desktop file and restore it later
• synchronize data with a desktop application
Note: The BlackBerry Desktop Software requires that backup data use the following format:
Length<2> Type<1> Data<n>
To ensure that the data is in the appropriate format, use one of the write methods in the
net.rim.device.api.synchronization.ConverterUtilities class.

Data backup
The BlackBerry Desktop Software provides a Backup and Restore tool that enables users to save
BlackBerry device data to a file on their desktop, and use this file to restore data to the BlackBerry
device.
When an application implements the synchronization API, the desktop software backs up and restores
the application database along with the other BlackBerry device databases. You can also use the
synchronization API to create data archives or to populate application databases when the BlackBerry
device first connects to the computer.

Data synchronization
The desktop software provides an Intellisync tool to synchronize the BlackBerry device with the
applications on the user computer.
Where backup and restore performs a bulk load of data between the BlackBerry device and a desktop
backup file, synchronization compares the data that exists in a desktop application with the data on the
BlackBerry device to merge the data.
To synchronize data with a desktop application, write a plug-in for the desktop software using the
BlackBerry Desktop API. The BlackBerry JDE also includes a sample synchronization application with a
desktop plug-in.
Note: There are no restrictions on the format that you use to store data for backup. The only requirement is that the
application read and write data in the format used by the desktop plug-in application.
BlackBerry Application Developer Guide

Synchronization API
Implement the following interfaces provided by the synchronization API:

Interface Description
SyncConverter converts data between the SyncObject format required on the BlackBerry device and a serialized format
required on the desktop
SyncCollection represents the collection of synchronization objects for an application
SyncObject represents an object that can be backed up and restored to the user computer

The SerialSyncManager class provides access to the synchronization manager, in particular to register
new objects for synchronization.
Note: To back up and restore a very small amount of data, such as application configuration options, you can extend the
SyncItem class and implement its abstract methods. The SyncItem class implements the SyncCollection,
SyncConverter, and SyncObject interfaces for you.

Adding support for backing up persistent

data
To support backup, modify a class that implements the Persistable interface to implement the
SyncObject interface.
Modify the main class for your application to implement the SyncCollection and SyncConverter
interfaces.
Note: The SyncCollection and SyncConverter interfaces can be implemented by the same class or by separate classes,
depending on the design of your application. The following sections explain how to implement these interfaces in the same
class.

Define a unique ID
Define a _uid variable. Your implementation of getUID() returns a unique ID to use for synchronization
operations.

Define a constructor
Your constructor implementation accepts a unique ID as a parameter and sets the _uid variable to this
value.
Note: Each synchronization object that is stored on the BlackBerry device must have an associated ID that is unique to its
application. The UIDGenerator sets this value ID by default.

Register a synchronization collection

In main(), register your SyncCollection with the synchronization manager. Create a separate project
to pass in the init argument when the BlackBerry device first starts. See “Registering a synchronization
collection when the BlackBerry device starts” on page 99 for more information.
public static void main(String[] args) {
boolean startup = false;
for (int i=0; i<args.length; ++i) {

98
 9: Backing up and restoring persistent data

if (args[i].startsWith("init")) {
startup = true;
}
}
if (startup) {
//enable application for synchronization on startup
SerialSyncManager.getInstance().enableSynchronization(new
RestaurantsSync());
} else {
RestaurantsSync app = new RestaurantsSync();
app.enterEventDispatcher();
}
}

Registering a synchronization collection when the

BlackBerry device starts
To register a synchronization collection when the BlackBerry device starts, create a separate project that
acts as an alternate entry point to your main application. This project passes an argument to your
application the first time that the BlackBerry device starts so that your application registers only once.

Creating an initialization project

1. In the IDE, create a project.
2. Right-click the project, and then click Properties.
3. Click the Application tab.
4. In the Project type drop-down list, click Alternate CLDC Application Entry Point.
5. In the Alternate entry point for drop-down list, click the project that implements synchronization.
6. In the Arguments passed to field, type init.
7. Select the Auto-run on startup option.
8. Select the System module option.
9. Click OK.
Note: Arguments can be passed to BlackBerry CLDC applications on startup; however, this functionality does not exist
for MIDLet applications.

Code example
This code example demonstrates how to enable desktop software to back up and restore persistent data
for your application. This example modifies the Restaurants.java code example to implement the
synchronization API.

Example: RestaurantsSync.java
/**
* RestaurantsSync.java
* Copyright (C) 2001-2005 Research In Motion Limited. All rights reserved.
*/

99
BlackBerry Application Developer Guide

package com.rim.samples.docs.restaurantssync;

import java.io.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.system.*;
import net.rim.device.api.util.*;
import java.util.*;
import net.rim.device.api.i18n.*;
import net.rim.device.api.synchronization.*;
import com.rim.samples.docs.resource.*;

import com.rim.samples.docs.baseapp.*;

public class RestaurantsSync extends BaseApp implements RestaurantsSyncResource,

SyncCollection, SyncConverter, KeyListener, TrackwheelListener {

private static final long KEY = 0xdec6a67096f833cL;

private AutoTextEditField namefield;

private AutoTextEditField addressfield;
private EditField phonefield;
private EditField specialtyfield;

private static PersistentObject store;

private static Vector _data;
private static ResourceBundle _resources;
private static final int FIELDTAG_NAME = 1;
private static final int FIELDTAG_PHONE = 2;
private static final int FIELDTAG_ADDRESS = 3;
private static final int FIELDTAG_SPECIALTY = 4;

private static RestaurantsSync _instance;

private MenuItem saveItem = new MenuItem(_resources, MenuItem.SAVE_CLOSE, 110,

10) {
public void run() {
RestaurantInfo info = new RestaurantInfo();
info.setElement(RestaurantInfo.NAME, namefield.getText());
info.setElement(RestaurantInfo.ADDRESS, addressfield.getText());
info.setElement(RestaurantInfo.PHONE, phonefield.getText());
info.setElement(RestaurantInfo.SPECIALTY, specialtyfield.getText());
_data.addElement(info);

synchronized(store) {
store.setContents(_data);
store.commit();
}
Dialog.inform(_resources.getString(APP_SUCCESS));
namefield.setText(null);
addressfield.setText(null);
phonefield.setText("");
specialtyfield.setText("");
}
};

100
 9: Backing up and restoring persistent data

private MenuItem getItem = new MenuItem("Get", 110, 11) {

public void run() {
synchronized(store) {
_data = (Vector)store.getContents();
if (!_data.isEmpty()) {
RestaurantInfo info = (RestaurantInfo)_data.lastElement();
namefield.setText(info.getElement(RestaurantInfo.NAME));
addressfield.setText(info.getElement(RestaurantInfo.ADDRESS));
phonefield.setText(info.getElement(RestaurantInfo.PHONE));
specialtyfield.setText(info.getElement(
RestaurantInfo.SPECIALTY));
}
}
}
};

static {
_resources = ResourceBundle.getBundle(RestaurantsSyncResource.BUNDLE_ID,
RestaurantsSyncResource.BUNDLE_NAME);
store = PersistentStore.getPersistentObject(KEY);
synchronized (store) {
_data = (Vector)store.getContents();
if ( _data == null ) {
_data = new Vector();
store.setContents( _data );
store.commit();
}
}

}
public static void main(String[] args) {
boolean startup = false;
for (int i=0; i<args.length; ++i) {
if (args[i].startsWith("init")) {
startup = true;
}
}

if (startup) {
// Enable application for synchronization on startup.
SyncManager.getInstance().enableSynchronization(
RestaurantsSync.getInstance());
} else {
RestaurantsSync app = new RestaurantsSync();
app.enterEventDispatcher();
}
}

public static RestaurantsSync getInstance() {

if (_instance == null) {
_instance = new RestaurantsSync();
}
return _instance;
}

101
BlackBerry Application Developer Guide

private static final class RestaurantInfo implements Persistable, SyncObject {

private String[] _elements; // Data.
public static final int NAME = 0;
public static final int ADDRESS = 1;
public static final int PHONE = 2;
public static final int SPECIALTY = 3;
private int _uid;

public int getUID() {

return _uid;
}

public RestaurantInfo() {
_elements = new String[4];
for ( int i = 0; i < _elements.length; ++i) {
_elements[i] = "";
}
}
public RestaurantInfo(int uid) {
_elements = new String[4];
for (int i = 0; i < _elements.length; ++i) {
_elements[i] = "";
}
_uid = uid;
}

public String getElement(int id) {

return _elements[id];
}

public void setElement(int id, String value) {

_elements[id] = value;
}
}

// SyncConverter methods.
public SyncObject convert(DataBuffer data, int version, int UID) {
try {
RestaurantInfo info = new RestaurantInfo(UID);
while(data.available() > 0) {
int length = data.readShort();
byte[] bytes = new byte[length];
switch (data.readByte()) {
case FIELDTAG_NAME:
data.readFully(bytes);
//trim null-terminator
info.setElement(RestaurantInfo.NAME,
new String(bytes).trim());
break;
case FIELDTAG_PHONE:
data.readFully(bytes);
info.setElement(RestaurantInfo.PHONE,
new String(bytes).trim());
break;
case FIELDTAG_ADDRESS:

102
 9: Backing up and restoring persistent data

data.readFully(bytes);
info.setElement(RestaurantInfo.ADDRESS,
new String(bytes).trim());
break;
case FIELDTAG_SPECIALTY:
data.readFully(bytes);
info.setElement(RestaurantInfo.SPECIALTY,
new String(bytes).trim());
break;
default:
data.readFully(bytes);
break;
}
}
return info;
} catch (EOFException e) {
System.err.println(e.toString());
}
return null;
}

public boolean convert(SyncObject object, DataBuffer buffer, int version) {

if (version == getSyncVersion()) {
if (object instanceof RestaurantInfo )
{
String name = ((RestaurantInfo)object).getElement(
RestaurantInfo.NAME);
String phone = ((RestaurantInfo)object).getElement(
RestaurantInfo.PHONE);
String address = ((RestaurantInfo)object).getElement(
RestaurantInfo.ADDRESS);
String specialty = ((RestaurantInfo)object).getElement(
RestaurantInfo.SPECIALTY);
buffer.writeShort(name.length()+1);
buffer.writeByte(FIELDTAG_NAME);
buffer.write(name.getBytes());
buffer.writeByte(0);
buffer.writeShort(phone.length()+1);
buffer.writeByte(FIELDTAG_PHONE);
buffer.write(phone.getBytes());
buffer.writeByte(0);
buffer.writeShort(address.length()+1);
buffer.writeByte(FIELDTAG_ADDRESS);
buffer.write(address.getBytes());
buffer.writeByte(0);
buffer.writeShort(specialty.length()+1);
buffer.writeByte(FIELDTAG_SPECIALTY);
buffer.write(specialty.getBytes());
buffer.writeByte(0);
return true;
}
}
return false;
}
public void beginTransaction() {

103
BlackBerry Application Developer Guide

store = PersistentStore.getPersistentObject(KEY);
_data = (Vector)store.getContents();
}
public void endTransaction() {
store.setContents(_data);
store.commit();
}
public SyncConverter getSyncConverter() {
return this;
}
public String getSyncName() {
return "Restaurant Synchronization Demo";
}
public String getSyncName(Locale locale) {
return getSyncName();
}
public int getSyncObjectCount() {
store = PersistentStore.getPersistentObject(KEY);
_data = (Vector)store.getContents();
return _data.size();
}
public SyncObject[] getSyncObjects() {
SyncObject[] array = new SyncObject[_data.size()];
for (int i = _data.size() - 1; i >= 0; --i) {
array[i] = (SyncObject)_data.elementAt(i);
}
return array;
}
public SyncObject getSyncObject(int uid) {
for (int i = _data.size() -1; i>= 0; --i) {
SyncObject so = (SyncObject)_data.elementAt(i);
if (so.getUID() == uid ) return so;
}
return null;
}
public int getSyncVersion() {
return 1;
}
public boolean addSyncObject(SyncObject object) {
_data.addElement(object);
return true;
}
public boolean removeAllSyncObjects() {
_data.removeAllElements();
return true;
}
public void clearSyncObjectDirty(SyncObject object) {
// Not applicable.
}
public boolean isSyncObjectDirty(SyncObject object) {
return false;
}
public boolean removeSyncObject(SyncObject object) {
return false;
}

104
 9: Backing up and restoring persistent data

public void setSyncObjectDirty(SyncObject object) {

}
public boolean updateSyncObject(SyncObject oldObject, SyncObject newObject) {
return false;
}
public RestaurantsSync() {
MainScreen mainScreen = new MainScreen();
mainScreen.setTitle(new LabelField(
_resources.getString(APPLICATION_TITLE)));
namefield = new AutoTextEditField(_resources.getString(FIELD_NAME), "");
addressfield = new AutoTextEditField( _resources.getString(FIELD_ADDRESS),
"");
phonefield = new EditField(
_resources.getString(FIELD_PHONE), "", Integer.MAX_VALUE,
BasicEditField.FILTER_PHONE);
specialtyfield = new EditField(_resources.getString(FIELD_SPECIALTY), "",
Integer.MAX_VALUE, BasicEditField.FILTER_DEFAULT);
mainScreen.add(namefield);
mainScreen.add(addressfield);
mainScreen.add(phonefield);
mainScreen.add(specialtyfield);
mainScreen.addKeyListener(this);
mainScreen.addTrackwheelListener(this);
pushScreen(mainScreen);
}
public void makeMenu( Menu menu, int instance) {
menu.add(saveItem);
menu.add(getItem);
super.makeMenu(menu, instance);
}
public void onExit() {
Dialog.alert(_resources.getString(APP_EXIT));
}
}

105
BlackBerry Application Developer Guide

106
 10
Accessing setup and
configuration information
• Service book API

Service book API

The service book API (net.rim.device.api.servicebook) enables applications to interact with the
BlackBerry infrastructure. The service book consists of service records, each of which defines a service
that can be enabled on a BlackBerry device.
Service records define the communication protocol (WAP or IPPP), network gateway, and configuration
information such as browser settings.

Service book API capability Description

Manage Mobile Data Service connections The browser application API can connect to the wireless network using any
ServiceBook entry with a UID of BrowserConfig. For example, the Browser class
uses the service book to retrieve a BrowserSession. Browser.getTransportUid()
queries the service book to retrieve the UID associated with a given service record.
Manage mail information The mail API enables applications to specify a channel through which to send e-mail
by referencing the appropriate service record. For example, applications can choose to
send messages using a BlackBerry Enterprise Server or a BlackBerry Internet Service.
See “Mail API” on page 11 for more information.

To view the service book on BlackBerry devices, users click Service Book under the handheld options.
The ServiceBook class maintains a collection of ServiceRecord objects. Each ServiceRecord object
is identified by a unique ID (UID) and connection ID (CID).

CID Description
CMIME The compressed multipurpose mail extensions (CMIME) CID defines messaging connections.
ALP The address lookup protocol (ALP) CID defines connections for wireless Global Address List searches.
IPPP The IP Proxy Protocol (IPPP) CID defines HTTP connections using the Mobile Data Service.
BrowserConfig The browser configuration (BrowserConfig) CID defines BlackBerry and WAP browser connections.
Sync The data synchronization (Sync) CID defines connections for wireless data synchronization.
WAP The wireless application protocol (WAP) CID defines WAP gateway connections.
CICAL The compressed iCalendar (CICAL) CID defines connections for wireless calendar synchronization.

Service record Description

Desktop [CMIME] This service record contains information that is required to send messages using the desktop and
perform other functions, such as wireless message reconciliation.
Desktop [ALP] This service record contains information required to perform wireless Global Address Book
searches.
Desktop [IPPP] This service record contains information that is required to use and browse the Internet using
the Mobile Data Service.
Desktop [CICAL] This service record contains information that is required to perform wireless calendar operations.
BlackBerry Application Developer Guide

Service record Description

Desktop [BrowserConfig] This service record contains configuration information for the BlackBerry Browser.
Web Client [CMIME] This service record contains information that is required to send messages and perform functions
(for example, wireless message reconciliation) using the BlackBerry Internet Service.
WAP Secure Transport [WAP] This service record contains information that is required to connect to a service provider’s
Wireless Application Protocol (WAP) gateway.
WAP Browser [BrowserConfig] This service record contains configuration information for the WAP Browser.
Desktop [Sync] This service record contains information that is required to perform data synchronization.

Listen for service book events

Your implementation of the GlobalEventListener interface (in the net.rim.device.api.system
package) enables your application to listen for service book events. Your implementation of
GlobalEventListener.eventOccurred() specifies the actions to perform when a global event is
received.
To register the global event listener, invoke
Application.addGlobalEventListener(GlobalEventListener).
The ServiceBook class defines the following global events, identified by global unique identifiers
(GUID).

GUID Description
GUID_SB_ADDED The GUID for the global event that is sent when a service book is added.
GUID_SB_BR_END The GUID for the global event that is sent when service book backup-restore ends.
GUID_SB_BR_START The GUID for the global event that is sent when service book backup-restore starts.
GUID_SB_CHANGED The GUID for the global event that is sent when a service book is changed.
GUID_SB_OTA_SWITCH The GUID for the global event that is sent when all service records are inserted due to a move
BlackBerry Enterprise Server command over the air.
GUID_SB_OTA_UPDATE The GUID for the global event that is sent when all service records are updated for a UID over the
air.
GUID_SB_REMOVED The GUID for the global event that is sent when a service book is deleted.

108
 11
Managing notifications
• Notification API
• Adding an event
• Responding to events
• Customizing system notifications

Notification API
The notification API (net.rim.device.api.notification) enables you to add custom events for your
application and define the type of notification that users receive when custom events occur.
Note: Check for a ControlledAccessException when your application first accesses the notification API. This runtime
exception is thrown if the system administrator restricts access to the notification API using application control. See the
BlackBerry Application Developer Guide Volume 1: Fundamentals for more information.

Notification event type Description

Immediate events system notification, such as flashing LED, vibration, or tune
Deferred events application-specific notification, such as a user interface

With immediate events, the BlackBerry device provides notification to the user as soon as the event
occurs, using a system notification, such as a flashing LED, vibration, or tune. An application cannot
request a specific type of notification. In the handheld profiles list, users control how they receive
notification of immediate events by choosing an active profile and setting profile options. To add custom
system notifications for immediate events, implement the Consequence interface.
With deferred events, the BlackBerry device schedules events in a queue according to their priority.
When the event occurs, applications that are affected by the event can provide a custom notification to
the user, typically by displaying a user interface element such as a dialog box. To listen for deferred
events, implement the NotificationsEngineListener interface. The BlackBerry device does not
provide system-wide notification for deferred events.

Adding events
Register a new event source
Create a unique long ID
Define a long ID for each notification event.
public static final long ID_1 = 0xdc5bf2f81374095L;
Note: Use the IDE to convert a String to a long to create a long identifier for your application:
1. In the IDE text pane, type a string.
2. Select the string, right-click, and then click Convert “string” to Long.
BlackBerry Application Developer Guide

Define a source object

Define an object that provides the source for the event. Your implementation of toString() returns the
string to display in the profiles list.
Object event = new Object() {
public String toString() {
return "Notification Demo";
}
}

Register your application as a notification source

To add your application to the handheld profiles list as the source of an event, invoke
NotificationsManager.registerSource(). In this method, specify a unique event ID, the source
object, and the notification level.
The notification level sets the priority of the event, which determines the order in which deferred events
occur. The levels, in order from highest to lowest priority, are as follows:
• NotificationsConstants.CRITICAL
• NotificationsConstants.SENSITIVE
• NotificationsConstants.IMPORTANT
• NotificationsConstants.DEFAULT_LEVEL
• NotificationsConstants.CASUAL

Note: The priority level applies to deferred events only. Immediate events occur as soon as they are triggered.
When you trigger a deferred event, you specify an expiry time. The user might not receive notification of a lower-priority
event, if the event expires before higher-priority events complete.

Registering the event source when the BlackBerry device starts

To register an event source, create a library project with libMain() to perform the registration when the
BlackBerry device starts.

Create a library project

1. In the IDE, create a project.
2. Right-click the project, and then click Properties.
3. Click the Application tab.
4. In the Project type drop-down list, click Library.
5. Select the Auto-run on startup option.
6. Click OK.
7. Define libMain().
public static final long ID_1 = 0xdc5bf2f81374095L;
public static final Object event = new Object() {
public String toString() { return "Sample Notification Event #1"; }
};
public static void libMain(String[] args) {
NotificationsManager.registerSource(ID_1, event,
NotificationsConstants.CASUAL);
}

110
 11: Managing notifications

Trigger an immediate event

Invoke triggerImmediateEvent(). Immediate events are indicated by standard system notifications,
such as tune, vibration, or LED.
NotificationsManager.triggerImmediateEvent(ID_1, 0, this, null);

The triggerImmediateEvent method accepts the following parameters:

Parameter Description
sourceID identifier of the application that starts the event (as specified when you invoked registerSource())
eventID application-specific event identifier
eventReference application-specific event cookie
context optional context object

In most cases, do not use immediate events because the BlackBerry device event notification does not
adequately indicate to the user what has happened. For example, if the BlackBerry device vibrates, it
would be difficult for the user to know whether an event has occurred in your application or whether a
new message has arrived. If you do use immediate events, consider implementing a custom notification,
such as a particular tune, to distinguish your application events from other BlackBerry device events. See
“Customizing system notifications” on page 116 for more information.

Trigger a deferred event

Invoke negotiateDeferredEvent(). A deferred event enables your application to notify the user with
a user interface element, such as a dialog box.
NotificationsManager.negotiateDeferredEvent(ID_1, 0, this, -1,
NotificationsConstants.MANUAL_TRIGGER, null);

The negotiateDeferredEvent(long, long, Object, long, int, Object) method accepts the
following parameters:

Parameter Description
sourceID identifier of the application that starts the event (as specified when you invoked registerSource())
eventID application-specific event identifier
eventReference application-specific event cookie
timeout event expiry time, in milliseconds, relative to time when the method is invoked (the timeout is ignored
unless the trigger is OUT_OF_HOLSTER_TRIGGER)
trigger either NotificationsConstants.OUT_OF_HOLSTER_TRIGGER, which specifies that the event occurs when
the BlackBerry device is disconnected from the computer; or
NotificationsConstants.MANUAL_TRIGGER, which specifies that the application itself triggers this
event
context optional object that can store additional, arbitrary parameters to control the state or behavior of an event
notification

If you invoke negotiateDeferredEvent(long, long, Object, long, int, Object), your

application must implement the NotificationEventListener to receive events and respond
appropriately. See “Responding to events” on page 115 for more information.

111
BlackBerry Application Developer Guide

Cancel an event
Cancel an immediate event
Invoke cancelImmediateEvent(long, long, Object, Object), and then specify the source and
event IDs.
NotificationsManager.cancelImmediateEvent(ID_1, 0, this, null);

Cancel a deferred event

Invoke cancelDeferredEvent(long, long, Object, int, Object), and then specify the source
and event ID.
NotificationsManager.cancelDeferredEvent(ID_1, 0, this,
NotificationsConstants.MANUAL_TRIGGER, null);

Cancel all deferred events

Invoke cancelAllDeferredEvents(long, int, Object) to cancel all deferred events that your
application started.
NotificationsManager.cancelAllDeferredEvents(ID_1,
NotificationsConstants.MANUAL_TRIGGER, null);
Note: If you invoke negotiateDeferredEvent() and do not specify a timeout, you must invoke
cancelDeferredEvent() to cancel the event, or the event never expires.

Code example
Example: NotificationDemo.java
/**
* NotificationsDemo.java
* Copyright (C) 2001-2005 Research In Motion Limited. All rights reserved.
*/

package com.rim.samples.docs.notifications;

import net.rim.device.api.notification.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.system.*;
import net.rim.device.api.util.*;
import com.rim.samples.docs.baseapp.*;

public class NotificationsDemo extends BaseApp {

public static final long ID_1 = 0xdc5bf2f81374095L;

private long _eventIdGenerator;
private static Object er;

public static final Object event = new Object() {

public String toString() {

112
 11: Managing notifications

return "Sample Notification Event #1";

}
};

public static void main(String[] args) {

NotificationsManager.registerSource(ID_1, event,
NotificationsConstants.CASUAL);
NotificationsManager.registerConsequence(ConsequenceDemo.ID, new
ConsequenceDemo());
NotificationsDemo app = new NotificationsDemo();
app.enterEventDispatcher();
}

public NotificationsDemo() {
MainScreen mainScreen = new MainScreen();
mainScreen.setTitle("Notification Demo App");
mainScreen.addKeyListener(this);
mainScreen.addTrackwheelListener(this);
NotificationsManager.registerNotificationsEngineListener(ID_1,
new NotificationsEngineListenerImpl(this));
pushScreen(mainScreen);
}

private MenuItem triggerItem = new MenuItem(null, 0, 100, 10) {

public void run() {
NotificationsManager.triggerImmediateEvent(ID_1, 0, this, null);
}
public String toString() {
return "Trigger event";
}
};

private MenuItem deferItem = new MenuItem(null, 0, 100, 10) {

public void run() {
long timeout = -1; // Ignored unless trigger is OUT_OF_HOLSTER_TRIGGER.
int trigger = NotificationsConstants.MANUAL_TRIGGER;
Object er = new Object();
NotificationsManager.negotiateDeferredEvent(ID_1, ++_eventIdGenerator,
er, timeout, trigger, null);
}
public String toString() {
return "Start deferred event";
}
};
private MenuItem cancelItem = new MenuItem(null, 0, 100, 10) {
public void run() {
int trigger = NotificationsConstants.MANUAL_TRIGGER;
NotificationsManager.cancelDeferredEvent(ID_1, _eventIdGenerator, er,
trigger, null);
}
public String toString() {
return "Cancel deferred event";
}
};

public void makeMenu( Menu menu, int instance ) {

113
BlackBerry Application Developer Guide

menu.add(triggerItem);
menu.add(deferItem);
menu.add(cancelItem);
super.makeMenu(menu, instance);
}

public void onExit() {

System.exit(0);
}

private static class NotificationsEngineListenerImpl implements

NotificationsEngineListener {
private UiApplication _app;
public NotificationsEngineListenerImpl(UiApplication app) {
_app = app;
}

public void deferredEventWasSuperseded(long sourceID, long eventID,

Object eventReference, Object context) {
final long _eventID = eventID;
er = eventReference;
_app.invokeLater(new Runnable() {
public void run() {
NotificationsManager.cancelDeferredEvent(ID_1, _eventID, er,
NotificationsConstants.MANUAL_TRIGGER, null);
}
});
}
public void notificationsEngineStateChanged(int stateInt, long sourceID,
long eventID, Object eventReference, Object context) {
if(stateInt == NotificationsConstants.OUT_OF_HOLSTER_ENGINE_STATE) {
// Perform some action if handheld is removed from holster.
}
if(stateInt == NotificationsConstants.IN_HOLSTER_ENGINE_STATE) {
// Perform some action if handheld is inserted into holster.
}
}
public void proceedWithDeferredEvent(long sourceID, long eventID,
Object eventReference, Object context) {
final long _eventID = eventID;
_app.invokeLater(new Runnable() {
public void run() {
String s = "This event has occurred: " + _eventID;
Dialog d = new Dialog(Dialog.D_OK, s, Dialog.OK,
Bitmap.getPredefinedBitmap(Bitmap.INFORMATION), 0);
d.show();
}
});
}
}
}

114
 11: Managing notifications

Responding to events
Your implementation of NotificationsEngineListener defines custom notification. Register your
implementation by invoking negotiateDeferredEvent(). You do not need to implement the listener if
you trigger immediate events, for which the BlackBerry device provides standard system notification.

Provide a custom UI notification for deferred events

Your implementation of the NotificationsEngineListener interface provides a custom UI
notification for deferred events. See the BlackBerry Application Developer Guide Volume 1:
Fundamentals for more information on creating user interfaces.
private static class ListenerImpl implements NotificationsEngineListener {...}

Define behavior if an event is superseded

Your implementation of deferredEventWasSuperseded() defines what happens if a deferred event is
superceded. This method is invoked when the event is superseded by another event at the same or
higher priority level. For example, you could cancel the event if it is superseded.
public void deferredEventWasSuperseded(long sourceID, long eventID, Object
eventReference, Object context) {
final long _eventID = eventID;
er = eventReference;
_app.invokeLater(new Runnable() {
public void run() {
NotificationsManager.cancelDeferredEvent(ID_1, _eventID, er,
NotificationsConstants.MANUAL_TRIGGER, null);
}
});
}

Define holstering behavior

Your implementation of notificationsEngineStateChanged() defines holstering behavior. This
method is invoked when the BlackBerry device is inserted in, or removed from, the holster. For example,
you could perform a specific action when a deferred event is scheduled and the BlackBerry device is
connected to, or disconnected from, the computer.
public void notificationsEngineStateChanged(int stateInt, long sourceID, long
eventID, Object eventReference, Object context) {
if(stateInt == otificationsConstants.OUT_OF_HOLSTER_ENGINE_STATE) {
// Perform action if BlackBerry device is removed from holster.
}
if(stateInt == NotificationsConstants.IN_HOLSTER_ENGINE_STATE) {
// Perform action if BlackBerry device is inserted into holster.
}
}

Define notification
Your implementation of proceedWithDeferredEvent() defines how to notify the user when the event
occurs, such as by displaying a dialog box. This method is invoked when the listener proceeds with the
event (no other higher priority events are in the queue).

115
BlackBerry Application Developer Guide

public void proceedWithDeferredEvent(long sourceID, long eventID, Object

eventReference, Object context) {
final long _eventID = eventID;
_app.invokeLater(new Runnable() {
public void run() {
String s = "This event has occurred: " + _eventID;
Dialog d = new Dialog(Dialog.D_OK, s, Dialog.OK,
Bitmap.getPredefinedBitmap(Bitmap.INFORMATION), 0);
d.show();
_eventHashtable.put(_eventID, d);
}
});
}

Register the notifications listener

Register your listener with the NotificationsManager by invoking
registerNotificationsEngineListener(int, NotificationsEngineListener). Provide as
parameters the event source ID of your application and an instance of the class that implements the
NotificationsEngineListener interface.
NotificationsManager.registerNotificationsEngineListener( ID_1, new
ListenerImpl(this));
Note: You can only register one NotificationsEngineListener for each application.

Customizing system notifications

Your implementation of the Consequence interface creates custom system notifications, such as a
particular tune, for immediate events or to perform other actions when events occur, such as creating a
log that counts the number of notifications received.
Note: The Consequence interface is used only for immediate events that require system notification. Deferred events
require your application to implement the NotificationsEngineListener and respond with an application-specific
response.
Provide an application on the Home screen to enable users to set notification options.

Respond to notification events

Your implementations of the Consequence and SyncConverter interfaces respond to notification
events. The Consequence interface defines an application response to notification events. The
SyncConverter interface defines the functionality required to convert data from object to serialized
format. It is required to enable the BlackBerry device to back up and restore profile configurations. See
"BlackBerry persistent storage" on page 84 for more information.
private static class ConsequenceImpl implements Consequence,SyncConverter {...}

Define a unique ID
Define a unique ID for this consequence.

116
 11: Managing notifications

public static final long ID = 0xbd2350c0dfda2a51L;

Define constants
Declare DATA and TYPE constants for the application. These constants are used when identifying the
type of incoming data from the SyncConverter when convert() is invoked. They are arbitrary
identifiers for data that is appropriate to this application.
private static final int TYPE = 'n' << 24 | 'o' << 16 | 't' << 8 | 'd';
private static final byte[] DATA = new byte[] {'m', 'y', '-', 'c',
'o', 'n', 'f', 'i', 'g', '-', 'o', 'b', 'j', 'e', 'c', 't'};
private static final Configuration CONFIG = new Configuration(DATA);

Create a tune
Create a tune to be played as part of the consequence for event notifications.
private static final short BFlat = 466; // 466.16
private static final short TEMPO = 125;
private static final short d16 = 1 * TEMPO;
private static final short dpause = 10; // 10 millisecond pause
private static final short[] TUNE = new short[] {BFlat, d16, pause, BFlat};
private static final int VOLUME = 80; // Percentage volume.

Define a notification
Your implementation of startNotification() defines the notification for this consequence. In the
following code sample, the LED flashes and a tune is played.
public void startNotification(long consequenceID, long sourceID, long eventID,
Object configuration, Object context) {
LED.setConfiguration(500, 250, LED.BRIGHTNESS_50);
LED.setState(LED.STATE_BLINKING);
Alert.startAudio(TUNE, VOLUME);
Alert.startBuzzer(TUNE, VOLUME);
}

Stop a notification
Your implementation of stopNotification() stops notification for this consequence.
public void stopNotification(long consequenceID, long sourceID,
long eventID, Object configuration, Object context) {
LED.setState(LED.STATE_OFF);
Alert.stopAudio();
Alert.stopBuzzer();
}

117
BlackBerry Application Developer Guide

Store user profile settings

Your implementation of newConfiguration() creates a new configuration object that stores user
profile settings. This object is passed to the consequence implementation to determine whether the type
of consequence that the user specified is appropriate for the event. The following code sample returns
the CONFIG object that you defined earlier.
public Object newConfiguration(long consequenceID, long sourceID,
byte profileIndex, int level, Object context) {
return CONFIG;
}

Enable BlackBerry device data backup

Your implementation of SyncConverter.convert() enables BlackBerry device data backup. This
method is invoked when data is backed up from the BlackBerry device to the user computer. The
following sample implementation reads incoming data from the DataBuffer and applies a 4-byte type
and length to the raw data.
public SyncObject convert(DataBuffer data, int version, int UID) {
try {
int type = data.readInt();
int length = data.readCompressedInt();
if ( type == TYPE ) {
byte[] rawdata = new byte[length];
data.readFully(rawdata);
return new Configuration(rawdata);
}
} catch (EOFException e) {
System.err.println(e);
}
return null;
}

Enable BlackBerry device data restore

Your implementation of SyncConverter.convert() enables BlackBerry device data restore. This
method is invoked when data is restored from the user computer to the BlackBerry device.
public boolean convert(SyncObject object, DataBuffer buffer, int version) {
boolean retval = false;
if ( object instanceof Configuration ) {
Configuration c = (Configuration)object;
buffer.writeInt(TYPE);
buffer.writeCompressedInt(c._data.length);
buffer.write(c._data);
retval = true;
}
return retval;
}

118
 11: Managing notifications

Define the notification configuration

Create a class that describes the notification configuration information. The class implements
SyncObject and Persistable. You must implement SyncObject.getUID() but your implementation
can return 0 if data synchronization is not required, as in the following example.
private static final class Configuration implements SyncObject, Persistable {
public byte[] _data;
public Configuration(byte[] data) {
_data = data;
}
public int getUID() {
return 0;
}
}

Register a consequence
If you create a custom Consequence implementation, register it with the NotificationsManager by
invoking registerNotificationsObjects(long, Consequence).
NotificationsManager.registerConsequence(ConsequenceImpl.ID, new
ConsequenceImpl());
To register the consequence when the BlackBerry device starts, perform this registration in a library
project. See “Registering the event source when the BlackBerry device starts” on page 110 for more
information.

Code example
Example: ConsequenceDemo.java
/**
* ConsequenceDemo.java
* Copyright (C) 2001-2005 Research In Motion Limited. All rights reserved.
*/

package com.rim.samples.docs.notifications;

import net.rim.device.api.synchronization.*;
import net.rim.device.api.notification.*;
import net.rim.device.api.system.*;
import net.rim.device.api.util.*;
import java.io.*;

public class ConsequenceDemo implements Consequence, SyncConverter {

public static final long ID = 0xbd2350c0dfda2a51L;

private static final int TYPE = ’n’ << 24 | ’o’ << 16 | ’t’ << 8 | ’d’;
private static final byte[] DATA = new byte[] {
’m’, ’y’, ’-’, ’c’, ’o’, ’n’, ’f’, ’i’,
’g’, ’-’, ’o’, ’b’, ’j’, ’e’, ’c’, ’t’ };

private static final Configuration CONFIG = new Configuration(DATA);

119
BlackBerry Application Developer Guide

private static final short BFlat = 466; // The actual value is 466.16.
private static final short TEMPO = 125;
private static final short d16 = 1 * TEMPO;
private static final short pause = 10; // 10 millisecond pause.
private static final short[] TUNE = new short[] {BFlat, d16, pause, BFlat};
private static final int VOLUME = 80; // Percentage volume.

public void startNotification(long consequenceID, long sourceID, long eventID,

Object configuration, Object context) {
LED.setConfiguration(500, 250, LED.BRIGHTNESS_50);
LED.setState(LED.STATE_BLINKING);

Alert.startAudio(TUNE, VOLUME);
Alert.startBuzzer(TUNE, VOLUME);
}

public void stopNotification(long consequenceID, long sourceID, long eventID,

Object configuration, Object context) {
LED.setState(LED.STATE_OFF);
Alert.stopAudio();
Alert.stopBuzzer();
}

public Object newConfiguration(long consequenceID, long sourceID,

byte profileIndex, int level, Object context) {
return CONFIG;
}

public SyncObject convert(DataBuffer data, int version, int UID) {

try {
int type = data.readInt();
int length = data.readCompressedInt();
if ( type == TYPE ) {
byte[] rawdata = new byte[length];
data.readFully(rawdata);
return new Configuration(rawdata);
}
} catch (EOFException e) {
System.err.println(e);
}
return null;
}
public boolean convert(SyncObject object, DataBuffer buffer, int version) {
boolean retval = false;
if ( object instanceof Configuration ) {
Configuration c = (Configuration)object;
buffer.writeInt(TYPE);
buffer.writeCompressedInt(c._data.length);
buffer.write(c._data);
retval = true;
}
return retval;
}

120
 11: Managing notifications

/* Inner class to store configuration profile. */

private static final class Configuration implements SyncObject, Persistable {

public byte[] _data;

public Configuration(byte[] data) {

_data = data;
}
public int getUID() {
return 0;
}
}
}

121
BlackBerry Application Developer Guide

122
 12
Managing applications
• Application manager
• Managing code modules
• Managing code modules

Application manager
The virtual machine (VM) on BlackBerry devices has an application manager that functions as the central
dispatcher of operating system events for other Java applications.
The net.rim.device.api.system.ApplicationManager class enables applications to interact with
the application manager to perform the following actions:
• interact with processes, such as retrieving the IDs for foreground applications
• post global events to the system
• lock or unlock the BlackBerry device, or determine whether the BlackBerry device is locked
• run an application immediately or at a specific time
To use any of the ApplicationManager methods, you must first retrieve a reference to the current
application manager by invoking getApplicationManager().
ApplicationManager manager = ApplicationManager.getApplicationManager();

Retrieve information about applications

Retrieve information about running processes by invoking the static method
ApplicationManager.getVisibleApplications(). For example, you could write a system
administration application that audits the state of the BlackBerry device to determine how long users
spend using each application.
To retrieve an array of ApplicationDescriptor objects for visible applications that are running, invoke
getVisibleApplications(). An ApplicationDescriptor object contains descriptive information for
the application, such as its name, icon, position on the Home screen, and resource bundle. Use
ApplicationDescriptor methods to retrieve this information. For example, to retrieve the name of a
running application, invoke getName() on an application descriptor.
ApplicationManager manager = ApplicationManager.getApplicationManager();
ApplicationDescriptor descriptors[] = manager.getVisibleApplications();
// Retrieve the name of a running application.
String appname1 = descriptors[0].getName();

To retrieve an ApplicationDescriptor for the current application, invoke

ApplicationDescriptor.currentApplicationDescriptor().

ApplicationDescriptor descriptor =
ApplicationDescriptor.currentApplicationDescriptor();
String appname = descriptor.getName();
BlackBerry Application Developer Guide

Post a global event

Use ApplicationManager.postGlobalEvent() as a basic mechanism to communicate with other
processes.
Note: You can also send and receive messages between processes using the runtime store. See “Sharing runtime objects
between applications” on page 129 for more information.

To post a global event to a particular application, invoke postGlobalEvent(int, long, int, int,
Object, Object).
The processID parameter specifies the ID of the process to which to post the event. To retrieve a
process ID, invoke getProcessId(ApplicationDescriptor). The guid parameter specifies a global
unique identifier (GUID) for the event. The data and object parameters specify additional information
for the event.
To post a global event to all applications, use one of the following forms of postGlobalEvent():

Method signature Description

boolean postGlobalEvent(long) posts a global event with a unique identifier
boolean postGlobalEvent(long, int, int) posts a global event with additional data
abstract boolean postGlobalEvent(long, int, int, Object, posts a global event with additional integer and object
Object) data

Receive a global event

Your implementation of the net.rim.device.api.system.GlobalEventListener interface receives
global events. Your implementation of GlobalEventListener.eventOccurred() defines what
happens when a global event occurs.
Register your implementation by invoking
Application.addGlobalEventListener(GlobalEventListener).

Lock the BlackBerry device

Invoke ApplicationManager.lockSystem(true).

Determine whether a BlackBerry device is locked

Invoke ApplicationManager.isSystemLocked().

Unlock a BlackBerry device

Invoke ApplicationManager.unlockSystem(true).

Run an application with different arguments

Create a new application descriptor
Use the existing ApplicationDescriptor as a template. Specify the arguments to use in main().

124
 12: Managing applications

ApplicationDescriptor template =
ApplicationDescriptor.currentApplicationDescriptor();
String[] args = { "admin", "secure" };
ApplicationDescriptor newdescriptor = new ApplicationDescriptor(template, args);

The ApplicationDescriptor constructor has two other forms:

Method signature Description

ApplicationDescriptor(ApplicationDescriptor, This form of the constructor enables you to specify a name for the
String, String[]) new ApplicationDescriptor.
ApplicationDescriptor(ApplicationDescriptor, This form of the constructor enables you to specify a name, and
String, String[], Bitmap, int, String, int) initial settings, including an application icon, a Home screen
position, and the resource bundle and ID to use for the application
title.

Run the application

Run the application using a new ApplicationDescriptor object.
ApplicationManager appmanager = ApplicationManager.getApplicationManager();
try {
appmanager.runApplication(newdescriptor);
} catch(ApplicationManagerException) {
// Handle error.
}

The runApplication() method creates a new process and invokes the exported main() method in the
specified descriptor, using its arguments. The new process moves to the foreground if possible.

Run an application at a specified time

Invoke scheduleApplication() instead of runApplication().
try {
appmanager.scheduleApplication(newdescriptor, 1728000, false);
} catch(ApplicationManagerException) {
// Handle error.
}

The scheduleApplication(ApplicationDescriptor, int, Boolean) method requires the

following parameters:
• an ApplicationDescriptor object
• time at which to start the application, in milliseconds
• a Boolean value, where true indicates that the time is absolute (calculated from midnight,
January 1, 1970 UTC), and false indicates that the time is relative to midnight local time
Note: The application does not run if the BlackBerry device is restarted or turned off before the specified time.

Managing code modules

The CodeModuleManager class, in the net.rim.device.api.system package, enables you to retrieve
information about and manage code modules on the BlackBerry device.

125
BlackBerry Application Developer Guide

A code module is a .cod file, the compiled archive of a single project in the IDE. To view a list of third-
party applications installed on BlackBerry devices, in the handheld options, click Applications. Click the
Properties menu item to view information about each application.

Retrieve module information

The CodeModuleManager class provides methods that enable applications to retrieve information about
code modules on the BlackBerry device, such as the name, type, description, version, and creation date.
To retrieve a handle for the module, invoke getModuleHandle(). Provide as a parameter the name of
the code module.
int handle = CodeModuleManager.getModuleHandle("test_module");

Invoke methods of the CodeModuleManager class to retrieve specific information. Provide 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 );

Retrieve an array of handles

To retrieve an array of handles for all existing modules on the BlackBerry device, invoke
getModuleHandles().

int handles[] = CodeModuleManager.getModuleHandles();

String name = CodeModuleManager.getModuleName( handles[0]);
The net.rim.device.api.system.CodeModuleManager class provides methods for creating, saving,
and deleting code modules. These capabilities enable an application on the BlackBerry device to receive
.cod files wirelessly.

Code module manager methods

Method Description
int handle = This method retrieves the handle of the module in which
CodeModuleManager.getModuleHandleForObject( anObject ); an object class is defined.
boolean library = CodeModuleManager.isLibrary( handle ); This method determines whether a module is a library.
This method returns true if the module is a library or
false if the module is an application.
int size = CodeModuleManager.getModuleHandleForObject( This method determines the size, in bytes, of the code
anObject); that a module contains.
ApplicationDescriptor descriptors[] = This method retrieves an array of all descriptors that a
CodeModuleManager.getApplicationDescriptiors( handle ); code module contains.

Create a module
Invoke createNewModule(). Provide the size of the module in bytes as a parameter.

126
 12: Managing applications

int handle = CodeModuleManager.createNewModule( 3000 );

This method returns the module handle or 0 if the module cannot be created.
To add data to the module when you create it, invoke the following form of createNewModule().
Provide as parameters the length in bytes of the entire module, a byte array to add to the module, and
the length parameter specifies the number of bytes from the byte array to add to the start of the
module.
static int createNewModule(int, byte[], int);

Write data into a module

Invoke writeNewModule(). Provide a byte array of data as a parameter to this method.
Boolean success = CodeModuleManager.writeNewModule( handle, data, 0, data.length );

Note: A module must have the correct format for a .cod file. You can write data into a code module in increments, as long
as you know the offset at which to add data.

Save a module to the BlackBerry device database

Invoke saveNewModule(int).
int result = CodeModuleManager.saveNewModule( handle );

The saveNewModule(int) method returns one of the result codes that are defined in the
CodeModuleManager class, such as CMM_OK if the module is saved successfully.

Delete a module from the BlackBerry device

database
Invoke deleteModuleEx(int, Boolean). Provide as parameters the handle of the module to delete
and a Boolean value to specify whether to delete the module and any data it contains or to delete the
module only if does not have any associated data. If the module is in use, it is deleted the next time that
the BlackBerry device is restarted.
int handle = CodeModuleManager.getModuleHandle("test_module");
if( handle != 0 ) {
Boolean success = CodeModuleManager.deleteModule( handle, true );
}

127
BlackBerry Application Developer Guide

128
 13
Sharing runtime objects
between applications
• Sharing runtime objects

Sharing runtime objects

Notes: Check for a NoClassDefFoundError when your application first accesses the runtime store. This error is thrown if
the system administrator restricts access to the runtime store using application control. See the BlackBerry Application
Developer Guide Volume 1: Fundamentals for more information.
BlackBerry devices use a runtime store to provide a central location in which applications can share
runtime objects. By default, only applications that have been digitally signed by RIM can access data in
the runtime store. Contact RIM for information on how to control access to your data.

Retrieve the runtime store

Invoke RuntimeStore.getRuntimeStore().
RuntimeStore store = RuntimeStore.getRuntimeStore();

To add or retrieve runtime objects, invoke methods on RuntimeStore.

Note: The runtime store is not persistent. If the BlackBerry device is restarted, data in the runtime store is lost.

Add a runtime object

Invoke RuntimeStore.put(long, String). Provide as parameters a unique long ID and the object to
store.
RuntimeStore store = RuntimeStore.getRuntimeStore();
// Create an object and a unique number to identify the object.
String msg = "Some shared text";
long ID = 0x60ac754bc0867248L;
// put() throws an IllegalArgumentException if an object with the same ID exists.
try {
store.put( ID, msg );
} catch(IllegalArgumentException e) {
// Handle exception - an object with the same ID exists.
}

Replace a runtime object

Invoke replace().
BlackBerry Application Developer Guide

RuntimeStore store = RuntimeStore.getRuntimeStore();

String newmsg = "Some new text";
try {
// Returns the existing object with the specified ID if it exists; null
// otherwise.
Object obj = store.replace( 0x60ac754bc0867248L, newmsg);
} catch(ControlledAccessException e) {
// Handle exception - insufficient permissions.
}

Retrieve a registered runtime object

Invoke RuntimeStore.get(). Provide as a parameter the object ID.
RuntimeStore store = RuntimeStore.getRuntimeStore();
// get() throws a ControlledAccessException if your application does not have read
access to the specified object.
try {
// get() returns the objectm with the specified ID if it exists; null
// otherwise.
Object obj = store.get(0x60ac754bc0867248L);
} catch(ControlledAccessException e) {
// Handle exception.
}

Retrieve an unregistered runtime object

Invoke RuntimeStore.waitFor() to wait for an object to be registered.
RuntimeStore store = RuntimeStore.getRuntimeStore();
try {
Object obj = store.waitFor(0x60ac754bc0867248L);
} catch(ControlledAccessException e) {
// Handle exception - insufficient permissions.
} catch(RuntimeException e) {
// Handle exception - time out.
}
Note: If the object with the specified ID does not exist, waitFor() blocks for a maximum of MAX_WAIT_MILLIS. The
waitFor() method throws a RuntimeException if the object is not registered by this time.

130
Glossary
A JAR
ALX Java Archive
Application Loader XML JRE
APN Java Runtime Environment
Access Point Name
K
C KVM
CA Kilobyte virtual machine
Certificate Authority L
cHTML LDAP
Compact Hypertext Markup Language Lightweight Directory Access Protocol
CLDC
LTPA
Connected Limited Device Configuration
Lightweight Third-Party Authentication
G
M
GUI MB
graphical user interface megabyte
GUID MHz
globally unique identifier megahertz
I MIDlet
i18n MIDP application
internationalization MIDP
IP Mobile Information Device Profile
Internet Protocol MIME
IPPP Multipurpose Internet Mail Extensions
IP Proxy Protocol O
ISDN OCSP
Integrated Services Digital Network Online Certificate Status Protocol
J P
JAD
PAP
Java Application Descriptor
Password Authentication Protocol
BlackBerry Application Developer Guide

PIM T
personal information management TCP
PIN Transmission Control Protocol
personal identification number TIFF
PNG Tag Image File Format
Portable Network Graphics TLS
Transport Layer Security
R
RRC U
Radio Resource Control UDP
RTC User Datagram Protocol
real-time clock URI
Uniform Resource Identifier
S
URL
SDK
Uniform Resource Locator
software development kit
UTC
SIM
Universal Time Coordinate
Subscriber Identity Module
SMS W
Short Message Service WAP
SRAM Wireless Application Protocol
static random access memory WBMP
SRP wireless bitmap
Service Relay Protocol WML
SSL Wireless Markup Language
Secure Sockets Layer WMLC
Wireless Markup Language Compiled
WTLS
Wireless Transport Layer Security

132
Index
A overriding constructor, 80
addCall(), PhoneLogs class, 76 toString(), 80
addElement(), Vector class, 91 ApplicationMenuItemRepository class
addGlobalEventListener(), Application class, 124 about, 80
addMenuItem(), ApplicationMenuItemRepository class, addMenuItem(), 81
81 getInstance(), 81
addPhoneListener(), Phone class, 74 applications
addRecordStore(), RecordStore class, 83 auto-run on startup, 99
address book different arguments, 124
about, 25 event source, 110
converting to serial formats, 28 inter-process communication, 124
creating contacts, 25 managing, 123
importing contacts, 28 retrieving information, 123
invoking, 79 scheduling, 125
opening ContactList, 25 system modules, 99
removing contacts, 29 See also code modules
retrieving contact information, 27 appointments, See calendar
saving contacts, 27 attachments
administrative control about, 19
about, 85 registering a handler, 20
APIs retrieving contents, 21
invocation, 79 retrieving information, 21
messaging, 11 sending, 21
notifications, 109 auto-run, applications, 99
persistence, 83
PIM, 23 B
service book, 107
backup
synchronization, 97 about, 85
Application class, addGlobalEventListener(), 124 implementing, 97
application descriptor, different arguments, 124 supporting, 98
application manager, virtual machine, 123
Backup and Restore
ApplicationDescriptor class
about, 97
about, 124
currentApplicationDescriptor(), 124 BlackBerry applications
adding menu items, 80
ApplicationManager class
about, 123 starting, 79
Boolean data type, persistence, 85
getVisibleApplications(), 123
browser
isSystemLocked(), 124
about, 47
lockSystem(), 124
API overview, 47
postGlobalEvent(), 124
Browser class
runApplication(), 125 getDefaultSession(), 47
scheduleApplication(), 125 getSession(), 47
unlockSystem(), 124 browser content
ApplicationMenuItem class filtered, 67
about, 80 retrieving, 51
extending, 80 browser fields, about, 48
BlackBerry Application Developer Guide

browser sessions, retrieving, 47 code modules

BrowserContentProvider class creating, 125
about, 62 deleting, 127
getAccept(), 63 methods, 126
getSupportedMIMETypes(), 63 retrieving handle arrays, 126
BrowserContentProvider interface retrieving handles, 126
getBrowserContent(), 63 retrieving information, 125
BrowserField class, finishLoading(), 52 saving, 127
BrowserPageContext interface, about, 63 writing, 127
BrowserSession class, displayPage(), 48 code signing
Byte data type, persistence, 85 about, 5
registering, 8
C
requesting signatures, 9
calendar verification, 6
adding appointment information, 37 CodeModuleManager class
converting to serial formats, 39 about, 125
creating a recurring appointment, 38 createNewModule(), 126
creating an appointment, 37 deleteModule(), 127
invoking, 79 getApplicationDescriptor(), 126
opening a list, 37 getModuleHandle(), 126
retrieving appointment information, 39 getModuleHandleForObject(), 126
saving an appointment, 38 getModuleHandles(), 126
See also PIM isLibrary(), 126
CalendarArguments class, about, 79 saveNewModule(), 127
call logs writeNewModule(), 127
adding, 76 commit(), PersistentObject class, 86
code example, 76 conference calls, about, 75
replacing, 76 ConferencePhoneCallLog class
callAt(), PhoneLogs class, 75 constructor, 76
cancelAllDeferredEvents(), NotificationsManager class, getParticipantAt(), 76
112 Consequence class
cancelDeferredEvent(), NotificationsManager class, 112 newConfiguration(), 118
cancelImmediateEvent(), NotificationsManager class, startNotification(), 117
112
stopNotification(), 117
Character data type, persistence, 85
.cod files, compiled projects, 9 Consequence interface
code examples about, 116
BasicMail.java, 17 ContactList class
about, 25
BrowserFieldSampleApp.java, 52
closing, 27
BrowserPlugin.java, 64
opening, 25
ConsequenceDemo.java, 119
convert(), SyncConverter class, 118
ContactsDemo.java, 29
createNewModule(), CodeModuleManager class, 126
DemoAppMenuItem.java, 81 .csl files, required signatures, 9
DemoOptionsProvider.java, 44 .cso files, optional signatures, 9
EventDemo.java, 40 currentApplicationDescriptor(), ApplicationDescriptor
NotificationsDemo.java, 112 class, 124
PhoneLogsDemo.java, 76 custom consequences, code example, 119
Protocol.java, 68 custom notifications
Restaurants.java, 92 about, 115
RestaurantsSync.java, 99 defining, 115
TaskDemo.java, 35 user profile settings, 118
UserInfo.java, 87 custom objects, managing, 90

134
 Index

D UserInfo.java, 87
data
persistent storage, 86 F
data integrity, 85 file extensions
data types .cod files, 9
persistence, 85 .csl files, 9
databases, creating persistent, 86 .cso files, 9
deferred events filtering URLs, 67
cancelling, 112 finishLoading(), BrowserField class, 52
cancelling all, 112 FolderEvent class, about, 13
code example, 112 folders
triggering, 111 listing, 18
deferredEventWasSuperseded(), managing, 18
NotificationsEngineListener interface, 115 saving messages, 19
deleteCall(), PhoneLogs class, 76 searching, 19
deleteModule(), CodeModuleManager class, 127
deleting, persistent databases, 87 G
display characteristics, specifying, 63
displayBrowserField(), RenderingApplication class, 48 get(), RuntimeStore class, 130
displayPage(), BrowserSession class, 48 getAccept(), BrowserContentProvider class, 63
DTMF tones, queueing, 74 getActiveCall(), Phone class, 73
getApplicationDescriptor(), CodeModuleManager class,
E 126
getBrowserContent(), BrowserContentProvider
email, See messages interface, 63
enableSynchronization(), SerialSyncManager class, 98 getBrowserField(), RenderingApplication interface, 51
entry points, alternate, 99 getContents(), PersistentObject class, 87
enumerateRecords(), RecordStore class, 84 getDefaultSession(), Browser class, 47
eventOcurred(), GlobalEvent interface, 124 getDisplayPhoneNumber(), PhoneCall class, 73
events getElapsedTime(), PhoneCall class, 73
adding, 109 getInstance()
calendar, 37 ApplicationMenuItem class, 81
cancelling, 112 OptionsProvider interface, 43
global, 124 SerialSyncManager class, 98
messaging, 13 getModuleHandle(), CodeModuleManager class, 126
phone, 74 getModuleHandles(), CodeModuleManager class, 126
service book, 108 getModuleManagerForObject(), CodeModuleManager
triggering deferred, 111 class, 126
examples getParticipantAt(), ConferencePhoneCallLog class, 76
BasicMail.java, 17 getParticipants(), PhoneCallLog class, 76
BrowserFieldSampleApp.java, 52 getRecord(), RecordStore class, 83
BrowserPlugin.java, 64 getRenderingOptions(), RenderingApplication
ConsequenceDemo.java, 119 interface, 49
getRuntimeStore(), RuntimeStore class, 129
ContactsDemo.java, 29
getSession(), Browser class, 47
DemoAppMenuItem.java, 81 getStatus(), PhoneCall class, 73
DemoOptionsProvider.java, 44 getSupportedMIMETypes(), BrowserContentProvider
EventDemo.java, 40 class, 63
NotificationsDemo.java, 112 getVisibleApplications(), ApplicationManager class, 123
PhoneLogsDemo.java, 76 global events, posting, 124
Protocol.java, 68 GlobalEventListener interface, about, 124
Restaurants.java, 92
RestaurantsSync.java, 99 H
TaskDemo.java, 35 handheld options

135
BlackBerry Application Developer Guide

about, 43 about, 11
adding, 43 attachments, 19
code example, 44 creating, 11
registering, 43 managing events, 13
storing data persistently, 44 managing folders, 18
using public methods, 44 multipart, 12
handhelds reading, 14
locking, 124 receiving, 13
unlocking, 124 replying, 16
Hashtable data type, persistence, 85 storing, 12
HTTP filters, about, 67 MIME types
HTTPFilterRegistry class, registerFilter(), 68 listing accepted, 63
supporting additional, 62
I
immediate events N
cancelling, 112 negotiateDeferredEvent(), Notifications manager class,
code example, 112 111
triggering, 111 newConfiguration(), Consequence class, 118
initialization projects, creating, 99 notifications
Integer data type, persistence, 85 about, 109
integrity, data, 85 adding events, 109
Intellisync, about, 97 canceling events, 112
intercepting, URLs, 67 custom, 115
inter-process communication, global events, 124
custom system, 116
Invoke class, invokeApplication(), 79
invokeApplication(), Invoke class, 79 custom system notifications, 116
isLibrary(), CodeModuleManager class, 126 deferred events, 111
isOutgoing(), PhoneCall class, 73 defining custom, 115
isSystemLocked(), ApplicationManager class, 124 holstering, 115
immediate events, 111
L listener, 115
lastElement(), Vector class, 92 registering listener, 116
library projects, creating, 110 superseded, 115
locking, handhelds, 124 triggering deferred events, 111
lockSystem(), ApplicationManager class, 124 tunes, 117
Long data type, persistence, 85 NotificationsEngineListener interface, 115
about, 115
M deferredEventWasSuperseded(), 115
managing, applications, 123 notificationsEngineStateChanged(), 115
memo pad, invoking, 79 registerNotificationsEngineListener(), 116
MemoArguments class, about, 79 notificationsEngineStateChanged(),
menu items NotificationsEngineListener interface, 115
adding, 80 NotificationsManager class
adding to BlackBerry applications, 80 cancelDeferredEvent(), 112
registering, 81 cancelImmediateEvent(), 112
specifying behavior, 80 code example, 112
specifying position, 80 negotiateDeferredEvent(), 111
specifying text, 80 registerNotificationsObject(), 119
MessageArguments class, about, 79 registerSource(), 110
MessageEvent class, about, 13 triggerImmediateEvent(), 111
messages numberOfCalls(), PhoneLogs class, 75

136
 Index

O getStatus(), 73
Object data type, persistence, 85 isOutgoing(), 73
openRecordStore(), RecordStore class, 83 PhoneCallLog class
options constructor, 76
See handheld options getParticipants(), 76
OptionsProvider interface PhoneCallLogID class
about, 43 about, 76
getInstance(), 43 PhoneListener interface, about, 74
registerOptionsProvider(), 43 PhoneLogs class
addCall(), 76
P callAt(), 75
deleteCall(), 76
persistence
getInstance(), 75
BlackBerry APIs, 84
swapCall(), 76
code examples, 92
PIM
creating databases, 86
fields, 23
custom objects, 90
items, 23
limited memory, 84
lists, 23
MIDP API, 83
See also address book, calendar, tasks
retrieving data, 87
postGlobalEvent(), ApplicationManager class, 124
retrieving objects, 92 proceedWithDeferredEvent(),
saving data, 86 NotificationsEngineListener interface, 115
saving objects, 91 put(), RuntimeStore class, 129
persistent data, managing, 85
persistent databases, deleting, 87 R
PersistentObject class
about, 86 receiving, messages, 13
record stores
commit(), 86
about, 83
getContents(), 87
adding, 83
setContents(), 86
opening, 83
PersistentStore class, about, 84
phone application, invoking, 79 retrieving, 83
phone calls retrieving all, 84
about, 73 RecordStore class
adding DTMF tones, 74 addRecordStore(), 83
duration, 73 enumerateRecords(), 84
retrieving, 73 getRecord(), 83
status, 73 openRecordStore(), 83
Phone class registerFilter(), HTTPFilterRegistry class, 68
addPhoneListener(), 74 registering
getActiveCall(), 73 attachment handler, 20
notification event source, 109
removePhoneListener(), 74
options items, 43
phone listener, registering, 74
phone logs startup, 110
about, 75 synchronization collections, 98
missed calls folder, 75 registerNotificationsEngineListener(),
normal calls folder, 75 NotificationsEngineListener class, 116
retrieving, 75 registerNotificationsObjects(), NotificationsManager
class, 119
PhoneArguments class, about, 79 registerOptionsProvider(), OptionsProvider interface, 43
PhoneCall class
registerSource(), NotificationsManager class, 110
about, 73
removePhoneListener(), Phone class, 74
getDisplayPhoneNumber(), 73 rendering
getElapsedTime(), 73

137
BlackBerry Application Developer Guide

separate threads, 48 service books

rendering options about, 107
specifying, 49 events, 108
rendering providers service records
registering, 62 about, 107
RenderingApplication class, displayBrowserField(), 48 setContents(), PersistentObject class, 86
RenderingApplication interface, Short data type, persistence, 85
getRenderingOptions(), 49 signing, See code signing
replace(), RuntimeStore class, 129 startNotification(), Consequence class, 117
restore stopNotification(), Consequence class, 117
about, 85 StoreEvent class, about, 13
impementing, 97 String data type, persistence, 85
supporting, 98 swapCall(), PhoneLogs class, 76
retrieving SyncCollection class
attachment contents, 21 registering, 98
attachment information, 21 SyncConverter class
root database, persistence, 86 convert(), 118
runApplication(), ApplicationDescriptor class, 125 notifications, 116
runtime APIs, about, 5 synchronization
runtime objects about, 97
retrieving, 129 collections, 98
sharing, 129 initializing, 99
runtime storage, 5 objects, 98
runtime store registering collections, 98
replacing objects, 129 SyncObject interface, about, 98
retrieving objects, 130
unregistered objects, 130 T
RuntimeStore class TaskArguments class, about, 79
get(), 130 tasks
getRuntimeStore(), 129 adding information, 32
put(), 129 code example, 35
replace(), 129 converting to serial formats, 34
waitFor(), 130 creating, 32
invoking, 79
S removing, 34
saveNewModule(), CodeModuleManager class, 127 retrieving information, 33
scheduleApplication(), ApplicationDescriptor class, 125 to do, See tasks
scheduling, applications, 125 toString(), ApplicationMenuItem class, 80
security triggerImmediateEvent(), NotificationsManager class,
about, 85 111
handheld lock, 124 tunes
See also code signing creating, 117
sending
attachments, 21 U
messages, 15 unique keys, creating, 86
serial formats unlocking, handhelds, 124
appointments, 39 unlockSystem(), ApplicationManager class, 124
contacts, 28 user profile settings, custom notifications, 118
tasks, 34
SerialSyncManager class V
enableSynchronization(), 98 Vector class
getInstance(), 98 addElement(), 91

138
 Index

lastElement(), 92 browser fields, 48

Vector data type, persistence, 85 displaying, 47
web pages
W displaying, 47
waitFor(), RuntimeStore class, 130 requesting, 48
web content writeNewModule(), CodeModuleManager class, 127

139
BlackBerry Application Developer Guide

140
©2005 Research In Motion Limited
Published in Canada.