LabelField title = new LabelField("UI Component Sample", LabelField.ELLIPSIS));
Task Create a field that lets a BlackBerry device user select a range of items in the list.
Steps 1. Create the items that you want to display in a ListField.
String fieldOne = new String("Mark Guo"); String fieldTwo = new String("Amy Krul");
2. Create an instance of a ListField.
ListField myList = new ListField();
3. Create an instance of a ListCallback.
ListCallback myCallback = new ListCallback();
4. Set the call back of the ListField to be the ListCallback.
myList.setCallback(myCallback);
5. Use the ListCallBack object to add items to the ListField.
myCallback.add(myList, fieldOne); myCallback.add(myList, fieldTwo);
6. Add the ListField to the MainScreen.

mainScreen.add(myList);

Create a field that displays a folder or tree relationship between items (such as documents or message folders).
A TreeField contains parent and child nodes. 1. To draw a TreeField, implement the TreeFieldCallback interface. 2. Specify whether a folder is collapsible by invoking TreeField.setExpanded() on the TreeField object.
String fieldOne = new String("Main folder");. TreeCallback myCallback = new TreeCallback(); TreeField myTree = new TreeField(myCallback, Field.FOCUSABLE); int node1 = myTree.addChildNode(0, fieldOne); int node2 = myTree.addChildNode(0, fieldTwo); int node3 = myTree.addChildNode(node2, fieldThree); int node4 = myTree.addChildNode(node3, fieldFour);. int node10 = myTree.addChildNode(node1, fieldTen); myTree.setExpanded(node4, false);. mainScreen.add(myTree);
Your implementation of TreeFieldCallback should add fields to the tree. See "Create a callback object" on page 33 for more information on callbacks.
private class TreeCallback implements TreeFieldCallback { public void drawTreeItem(TreeField _tree, Graphics g, int node, int y, int width, int indent) { String text = (String)_tree.getCookie(node); g.drawText(text, indent, y); } }
Creating custom UI components
To create custom fields, content menus, layout managers, and lists, use the BlackBerry APIs.

Create a custom field

Task Create a custom field. Steps You can only add custom context menu items and custom layouts to a custom field. > Extend the Field class, or one of its subclasses, implementing the DrawStyle interface to specify the characteristics of the custom field and turn on drawing styles.
public class CustomButtonField extends Field implements DrawStyle { public static final int RECTANGLE = 1; public static final int TRIANGLE = 2; public static final int OCTAGON = 3; private String _label; private int _shape; private Font _font; private int _labelHeight; private int _labelWidth; }

Load content in the 1. To download content for future playback, invoke MediaManager.createMediaLater(). background, and play it when 2. In MediaListener.mediaEvent(), add code to manage the MEDIA_REALIZED event that occurs the download is complete. when the content the application downloads finishes loading on the BlackBerry device. 3. To register the content that the data parameter specifies, invoke MediaPlayer.setMedia(data). 4. To start playback, invoke MediaPlayer.start().
manager.createMediaLater("http://webserver/sample.pme"); public void mediaEvent(Object sender, int event, int eventParam, Object data) { switch(event) {. case MEDIA_REALIZED: try { player.setMedia(data); player.start(); } catch(MediaException me) { System.out.println("Error playing media + me.getCode() + me.getMessage()); } break; } }
Track the progress of a download.
Extend the net.rim.plazmic.mediaengine.io.LoadingStatus class.
2. In your implementation of mediaEvent(), when the MEDIA_IO event occurs, cast the Object in the data parameter to a LoadingStatus object. 3. To retrieve the download status, and manage each status, invoke LoadingStatus.getStatus(). 4. For each normal status, print a message to the console.
Manage a failed download.
For the LOADING_FAILED status, perform the following actions: 1. To retrieve the error code, invoke LoadingStatus.getCode(). 2. To retrieve the detailed message, invoke LoadingStatus.getMessage(). 3. To retrieve the URL string of the content, invoke LoadingStatus.getSource().
Code fragment: Managing rich media content download events
Example: Code fragment: Managing rich media content download events
public void mediaEvent(Object sender, int event, int eventParam, Object data) { switch(event) {. case MEDIA_IO: { LoadingStatus s = (LoadingStatus)data; }. break; } break;. switch(s.getStatus()) { case LoadingStatus.LOADING_STARTED:
System.out.println("Loading in progress"); break; case LoadingStatus.LOADING_READING: System.out.println("Parsing in progress"); break; case LoadingStatus.LOADING_FINISHED: System.out.println("Loading completed"); break; case LoadingStatus.LOADING_FAILED: String errorName = null; int code = s.getCode(); switch (code) { case MediaException.INVALID_HEADER: errorName = "Invalid header" + "\n" + s.getSource(); break; case MediaException.REQUEST_TIMED_OUT: errorName = "Request timed out" + "\n" + s.getSource(); break; case MediaException.INTERRUPTED_DOWNLOAD: break; case MediaException.UNSUPPORTED_TYPE: errorName = "Unsupported type" + s.getMessage() + "\n" + s.getSource(); break; default: { if (code > 200) { // A code > 200 indicates an HTTP error errorName = "URL not found"; } else { // default unidentified error errorName = "Loading Failed"; } errorName += "\n" + s.getSource() + "\n" + s.getCode() + ": " + s.getMessage(); break; } } System.out.println(errorName); break; } // End switch s.getStatus(). break; }

Code sample: Drawing a new bitmap using an existing bitmap
To draw a new bitmap image, the DrawDemo.java sample retrieves raw data from a predefined bitmap image. It then displays the original and restored images.

Example: DrawDemo.java

/* * DrawDemo.java * Copyright (C) 2002-2005 Research In Motion Limited. */ package com.rim.samples.docs.drawing; import import import import net.rim.device.api.system.*; net.rim.device.api.ui.*; net.rim.device.api.ui.component.*; net.rim.device.api.ui.container.*;
/* The DrawDemo.java sample retrieves raw data from a predefined bitmap image, and then draws a new bitmap using the data. It then displays the original and restored images. */ public class DrawDemo extends UiApplication {
public static void main(String[] args) { DrawDemo app = new DrawDemo(); app.enterEventDispatcher(); } public DrawDemo() { pushScreen(new DrawDemoScreen()); } } final class DrawDemoScreen extends MainScreen { public DrawDemoScreen() { super(); LabelField title = new LabelField(UI Demo, LabelField.USE_ALL_WIDTH); setTitle(title); Bitmap original = Bitmap.getPredefinedBitmap(Bitmap.INFORMATION); Bitmap restored = new Bitmap(original.getType(), original.getWidth(), original.getHeight()); Graphics graphics = new Graphics(restored); // Retrieve raw data from original image. int[] argb = new int[original.getWidth() * original.getHeight()]; original.getARGB(argb, 0, original.getWidth(), 0, 0, original.getWidth(), original.getHeight()); // Draw new image using raw data retrieved from original image. try { graphics.drawRGB(argb, 0, restored.getWidth(), 0, 0, restored.getWidth(), restored.getHeight()); } catch(Exception e) { System.out.println(Error occurred during drawing: + e); } if(restored.equals(original)) { System.out.println(Success! Bitmap renders correctly with RGB data.); } else if(!restored.equals(original)) { System.out.println(Bitmap rendered incorrectly with RGB data.); } BitmapField field1 = new BitmapField(original, BitmapField.STAMP_MONOCHROME); BitmapField field2 = new BitmapField(restored); add(new LabelField(Original bitmap: )); add(field1); add(new LabelField(Restored bitmap: )); add(field2); } }
Code sample: Retrieving and displaying a rich media file
The MediaSample.java sample retrieves a.pme file from a web server and displays it on the BlackBerry device.
Example: MediaSample.java
/** * MediaSample.java * Copyright (C) 2001-2005 Research In Motion Limited. All rights reserved. */ package com.rim.samples.docs.mediasample; import import import import import java.io.*; net.rim.device.api.ui.*; net.rim.device.api.ui.component.*; net.rim.device.api.ui.container.*; net.rim.device.api.system.*;

// we want to let any collection listeners we have that the collection has been changed for( int i=0; i<_listeners.size(); i++ ) { CollectionListener cl = (CollectionListener)_listeners.elementAt( i ); cl.elementAdded( this, object ); } return true; } public boolean updateSyncObject(SyncObject oldObject, SyncObject newObject) { return false; //na - this method would look much the same as addSyncObject } public boolean removeSyncObject(SyncObject object) { return false; //na - this method would look much the same as addSyncObject } public boolean removeAllSyncObjects() { return false; //na } public SyncObject[] getSyncObjects() { SyncObject[] contactArray = new SyncObject[_contacts.size()]; for (int i = _contacts.size() - 1; i >= 0; --i) { contactArray[i] = (SyncObject)_contacts.elementAt(i); } return contactArray; } public SyncObject getSyncObject(int uid) { for (int i = _contacts.size() - 1; i >= 0; --i) { SyncObject so = (SyncObject)_contacts.elementAt(i); if ( so.getUID() == uid ) return so; } return null; } public boolean isSyncObjectDirty(SyncObject object) { return false; //na } public void setSyncObjectDirty(SyncObject object) { //na } public void clearSyncObjectDirty(SyncObject object) { //na
} public int getSyncObjectCount() { _persist = PersistentStore.getPersistentObject(PERSISTENT_KEY); _contacts = (Vector)_persist.getContents(); return _contacts.size(); } public int getSyncVersion() { return 1; } public String getSyncName() { return OTABackupRestoreContacts; } public String getSyncName(Locale locale) { return null; } public SyncConverter getSyncConverter() { return this; } public void beginTransaction() { _persist = PersistentStore.getPersistentObject(PERSISTENT_KEY); _contacts = (Vector)_persist.getContents(); } public void endTransaction() { _persist.setContents(_contacts); _persist.commit(); } //OTASyncCapable methods --------------------------------------------------public SyncCollectionSchema getSchema() { // returns our schema return _schema; } //CollectionEventSource methods -------------------------------------------public void addCollectionListener(Object listener) { _listeners = ListenerUtilities.fastAddListener( _listeners, listener ); } public void removeCollectionListener(Object listener) { _listeners = ListenerUtilities.removeListener( _listeners, listener ); }
public int size() { return _contacts.size(); } public ContactData contactAt( int index ) { return (ContactData)_contacts.elementAt( index ); } }
Code sample: Letting the BlackBerry Desktop Software to back up and restore BlackBerry Java Application data
Example: RestaurantsSync.java
/** * RestaurantsSync.java * Copyright (C) 2001-2005 Research In Motion Limited. All rights reserved. */ package com.rim.samples.docs.restaurantssync; import import import import import import import import import import java.io.*; net.rim.device.api.ui.*; net.rim.device.api.ui.component.*; net.rim.device.api.ui.container.*; net.rim.device.api.system.*; net.rim.device.api.util.*; java.util.*; net.rim.device.api.i18n.*; net.rim.device.api.synchronization.*; com.rim.samples.docs.resource.*;

int status = httpConn.getResponseCode(); switch (status) case (HttpConnection.HTTP_UNAUTHORIZED);
int status = httpConn.getResponseCode();
2. Create a run()method and within it implement a dialog object to ask the BlackBerry device user for login information.
UiApplication.getUiApplication().invokeAndWait(new Runnable()) { public void run() { dialogResponse = Dialog.ask; (Dialog.D_YES_NO,"Unauthorized Access:\n Do you wish to log in?"); } }
Process the response of the BlackBerry device user.
Create code that manages a Yes dialog response.
if (dialogResponse == Dialog.YES) {String login = "username:password"; //Close the connection. s.close();
2. Retrieve the login information and close the current connection.
3. Encode the login information.
byte[] encoded = Base64OutputStream.encode(login.getBytes(), 0, login.length(), false, false);
Use the BlackBerry device user login information to access the protected resource.
Open a new HTTPConnection and add the authorization header by invoking HTTPConnection.setRequestProperty()using the encoded login information.
s = (StreamConnection)Connector.open("http://mysite.com/ myProtectedFile.txt "); httpConn = (HttpConnection)s; httpConn.setRequestProperty("Authorization", "Basic " + new String(encoded));
Code fragment: Using HTTP authentication to connect to a protected internet resource
Example: Using HTTP authentication to connect to a protected Internet resource
HttpConnection httpConn = null; StreamConnection s = null; boolean keepGoing = true; int dialogResponse; try { s = (StreamConnection)Connector.open("http://mysite.com/myProtectedFile.txt"); httpConn = (HttpConnection)s; while(keepGoing) { int status = httpConn.getResponseCode(); switch (status) { case (HttpConnection.HTTP_OK): //Connection is 200 OK. //Download and process data. keepGoing = false; break; case (HttpConnection.HTTP_UNAUTHORIZED): //Connection is 401 UnAuthorized. //A login and password is required. //Retrieve the login information from somewhere. //You could prompt the user for this information or //retrieve this from elsewhere if it is saved within //your application. //Login information is hard coded here for brevity, but //we ask the user if they want to log-in. UiApplication.getUiApplication().invokeAndWait(new Runnable() { public void run() { dialogResponse = Dialog.ask (Dialog.D_YES_NO,"Unauthorized Access:\n Do you wish to log in?"); } }); if (dialogResponse == Dialog.YES) { String login = "username:password"; //Close the connection.

Close the Socket connection.
Invoke close() on the input and output streams and the socket connection.
_in.close(); _out.close(); conn.close();
Each of the close() methods throws an IOException. Make sure that the BlackBerry Java Application implements exception handling.

Datagram connections

Datagrams are independent packets of data that applications send over networks. A Datagram object is a wrapper for the array of bytes that is the payload of the datagram. Use a datagram connection to send and receive datagrams.

Use datagram connections

To use a datagram connection, you must have your own infrastructure to connect to the wireless network, including an APN for GPRS networks. Using UDP connections requires that you work closely with service providers. Verify that your service provider supports UDP connections.
Task Before opening a datagram connection, verify that the BlackBerry device is in network coverage. Steps > Use the CoverageInfo class and CoverageStatusListener interface of the net.rim.device.api.system package to make sure that the BlackBerry device is in network coverage.
Even though the CoverageInfo class and the CoverageStatusListener interface can determine if the BlackBerry device that your BlackBerry Java Application is on is in network coverage, they cannot guarantee that a subsequent network connection will be successful. Open a datagram connection. 1. Invoke Connector.open(), specifying udp as the protocol. 2. Cast the returned object as a DatagramConnection object.
(DatagramConnection)Connector.open("udp://host:dest_port[;src_port]/ apn");
where: Receive datagrams from all ports at the specified host. Open a datagram connection on a nonGPRS network. > > host is the host address in dotted ASCII-decimal format. dest-port is the destination port at the host address (optional for receiving messages). src-port is the local source port (optional). apn is the network APN in string format. Omit the destination port in the connection string. Specify the source port number, including the trailing slash mark. For example, the address for a CDMA network connection would be udp:// 121.0.0.0:2332;6343/. You can send and receive datagrams on the same port. Create a datagram. Add data to a diagram. > > Invoke DatagramConnection.newDatagram(). Invoke Datagram.setData().

private void insert(final String msg, final int offset) { invokeLater(new Runnable() { public void run() { _infoField.setCursorPosition(offset); _infoField.insert(msg); } }); }
private void remove(final int offset, final int count) { invokeLater(new Runnable() { public void run() { _infoField.setCursorPosition(offset+count); _infoField.backspace(count); } }); } }
Working with Wi-Fi connections on a BlackBerry device
Work with wireless access families Work with a Wi-Fi connection
Work with wireless access families
Working with the BlackBerry device transceiver involves using APIs that make reference to wireless access families. See the API reference for the BlackBerry Java Development Environment for more information about wireless access families.
Wireless access family 3GPP CDMA WLAN Description includes GPRS, EDGE, UMTS, GERAN, UTRAN, and GAN includes CDMA1x and EVDO includes 802.11, 802.11a, 802.11b, 802.11g
Identify the wireless access families that a BlackBerry device supports
Task Retrieve the wireless access families that a BlackBerry device supports. Determine if a BlackBerry device supports one or more wireless access families. Determine the wireless access family transceivers that are turned on. Steps > > Invoke RadioInfo.getSupportedWAFs(). Invoke RadioInfo.areWAFsSupported(int wafs).
Invoke RadioInfo.getActiveWAFs().
Turn on a transceiver for a wireless access family
Task Turn on the transceiver for a wireless access family. Turn off the transceiver for a wireless access family. Steps > > Invoke Radio.activateWAFs(int WAFs). The WAFs parameter is a bitmask. Invoke Radio.deactivateWAFs(int WAFs). The WAFs parameter is a bitmask.
Receive notifications of transceiver events
Task Enable a BlackBerry Application to receive transceiver events from multiple transceivers. Determine the wireless access family that generated a transceiver event. Steps > Register a transceiver event listener for specific wireless access families by invoking
Application.addRadioListener(int wafFilter, RadioListener listener).
This method registers the listener to listen for events from the wireless access families specified in the wafFilter parameter. This parameter is applied only to RadioStatusListeners. If a BlackBerry Application registers a RadioStatusListener method for more than one wireless access family, when the RadioStatusListener method notifies the application of a transciever event, the application will not be able to determine the wireless access family that generated the transciever event. > Register a unique RadioStatusListener instance for each wireless access family. Invoke Application.addRadioListener(int wafFilter, RadioListener listener) using the RadioInfo.WAF_WLAN parameter. From the net.rim.device.api.system package, import the WLANListener and WLANConnectionListener interfaces and the WLANInfo class. Invoke Application.addRadioListener(int wafFilter, RadioListener listener) using the RadioInfo.WAF_WLAN field and a RadioStatusListener object as parameters.

Retrieve the total count of unread messages in all folders in the store.
Invoke net.rim.blackberry.api.mail.Store.getUnreadMessageCount().
int numUnread = store.getUnreadMessageCount();
Task Get more of a message.
Steps By default, the first section of a message (typically about 2 KB) is sent to the BlackBerry device. 1. Create an instance of a subclass of the BodyPart abstract class.
TextBodyPart tb = new TextBodyPart(new MultiPart());
2. To determine if more data for a body part is available on the server, invoke tb.hasMore(). 3. To determine if the BlackBerry device user made a request for more data, invoke tb.moreRequestSent(). 4. To obtain a Transport object, invoke Session.getTransport() and store the returned object in a variable of type Transport.
Transport trans = Session.getTransport();
5. To request more of a message, invoke trans.more(BodyPart bp, boolean reqAll). 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).
if (( tb.hasMore() ) && (! tb.moreRequestSent()) {trans.more(tb, true);}

Open a message

1. Retrieve the message store and the folder that contains the message.
Store store = Session.waitForDefaultSession.getStore(); Folder folder = Store.getFolder("SampleFolder");
2. Retrieve the message objects from the folder. Iterate through the array and retrieve information, such as the sender and subject, to display to the BlackBerry device user.
Message[] msgs = folder.getMessages();
3. When a BlackBerry device 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 BlackBerry device 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(); Object o = msg.getContent(); // Verify that the message is not multipart. if ( o instanceof String ) { String body = (String)o;} //.

Retrieve attachments

Task Steps Invoke SupportedAttachmentPart.getContent().
String s = new String((byte[])p.getContent());
Retrieve the contents of an attachment. >
Task Retrieve information about the attachment.
Steps > Invoke the methods of the SupportedAttachmentPart class. The SupportedAttachmentPart class represents an attachment with a corresponding viewer on the BlackBerry device. An UnsupportedAttachmentPart represents an attachment that does not have a viewer on the BlackBerry device.
Send a message with an attachment
Task Create a multipart message. Steps
> Create a new Multipart object.
byte[] data = new byte[256]; // The attachment. MultiPart multipart = new MultiPart(); // Default type of multipart/mixed.
Create each component of the attachment.
Create a SupportedAttachmentPart object, designating the Multipart object as its parent.
SupportedAttachmentPart attach = new SupportedAttachmentPart( multipart, "application/x-example", "filename", data);
Add each SupportedAttachmentPart object to the multipart object. Set the content of the attachment.
Invoke addBodyPart(SupportedAttachmentPart) on that object. Invoke setContent(Multipart) on the Message object and provide as a parameter the Multipart object. Invoke Session.getTransport() and store the returned object in a variable of type Transport. The Transport object represents the messaging transport protocol.
multipart.addBodyPart(attach); // Add the attachment to the multipart.
msg.setContent(multipart);

Using PIM applications

Using the calendar Using the address book Using tasks Code samples

Using the calendar

Start the calendar from your BlackBerry Java Application
Task Open the calendar. View or change an event. Steps > 1. Invoke Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments). Retrieve an Event from the list of events.
Event e = null; EventList el = (EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST, PIM.READ_WRITE ); Enumeration events = el.items(); e = (Event)events.nextElement();
2. Invoke Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments) using the CalendarArguments object created using the ARG_VIEW_DEFAULT property and the retrieved Event.
Invoke.invokeApplication( Invoke.APP_TYPE_CALENDAR, new CalendarArguments( CalendarArguments.ARG_VIEW_DEFAULT, e ) );

Manage exceptions

Check for a ControlledAccessException if your BlackBerry Java Application invokes a BlackBerry application that you do not have permission to use or access.
Task Open a new populated event.
Steps 1. Create a new Event using an EventList object.
Event e = null; EventList el = (EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST, PIM.READ_WRITE ); e = el.createEvent();

Code sample: Retrieving strings from a resource file
Example: CountryInfo.java (with localization support)
/* This sample demonstrates how to store text strings in separate resource files for specific locales rather than providing text strings directly in the code. In your source code, you retrieve the string from the resource to display the appropriate text for the user locale. */ public class CountryInfo extends UiApplication { public static void main(String[] args) { CountryInfo theApp = new CountryInfo(); theApp.enterEventDispatcher(); } public CountryInfo() { pushScreen(new HelloWorldScreen()); } } final class HelloWorldScreen extends MainScreen implements CountryInfoResource { private InfoScreen _infoScreen; private ObjectChoiceField choiceField; private int select; private static ResourceBundle _resources = ResourceBundle.getBundle( CountryInfoResource.BUNDLE_ID, CountryInfoResource.BUNDLE_NAME); public HelloWorldScreen() { super(); LabelField title = new LabelField(_resources.getString(APPLICATION_TITLE), LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH); setTitle(title); add(new RichTextField(_resources.getString(FIELD_TITLE))); String choices[] = _resources.getStringArray(FIELD_COUNTRIES); choiceField = new ObjectChoiceField( _resources.getString(FIELD_CHOICE), choices); add(choiceField);
} public boolean onClose() { Dialog.alert(_resources.getString(CLOSE)); System.exit(0); return true; } private MenuItem _viewItem = new MenuItem(_resources, MENUITEM_VIEW, 110, 10) { public void run() { select = choiceField.getSelectedIndex(); _infoScreen = new InfoScreen(); UiApplication.getUiApplication().pushScreen(_infoScreen); } }; private MenuItem _closeItem = new MenuItem(_resources, MENUITEM_CLOSE, 200000, 10) { public void run() { onClose(); } }; protected void makeMenu( Menu menu, int instance ) { menu.add(_viewItem); menu.add(_closeItem); } private class InfoScreen extends MainScreen { public InfoScreen() { super(); LabelField lf = new LabelField(); BasicEditField popField = new BasicEditField( _resources.getString(FIELD_POP), null, 20, Field.READONLY); BasicEditField langField = new BasicEditField( _resources.getString(FIELD_LANG), null, 20, Field.READONLY); BasicEditField citiesField = new BasicEditField( _resources.getString(FIELD_CITIES), null, 50, Field.READONLY); add(lf); add(new SeparatorField()); add(popField); add(langField); add(citiesField); if (select == 0) { lf.setText(_resources.getString(FIELD_US)); popField.setText(_resources.getString(FIELD_US_POP)); langField.setText(_resources.getString(FIELD_US_LANG)); citiesField.setText(_resources.getString(FIELD_US_CITIES)); } else if (select == 1) { lf.setText(_resources.getString(FIELD_CHINA)); popField.setText(_resources.getString(FIELD_CHINA_POP)); langField.setText(_resources.getString(FIELD_CHINA_LANG)); citiesField.setText(_resources.getString(FIELD_CHINA_CITIES)); } else if (select == 2) { lf.setText(_resources.getString(FIELD_GERMANY)); popField.setText(_resources.getString(FIELD_GERMANY_POP)); langField.setText(_resources.getString(FIELD_GERMANY_LANG)); citiesField.setText(

Expand objects

In the threads pane, the following fields indicate the status of an object: thread that currently owns the object (Thread owning lock: @nnnnnnnn) thread that calls Object.wait() (Thread waiting for notify: @nnnnnnnn) thread that attempts to enter a synchronized block for the object (Thread acquiring lock: @nnnnnnnn)
Note: Threads, and objects whose threads are deadlocked, also display in the following panes: objects, local variables, watch, static data, processes and locks. To update the context of the selected thread in all the debugging panes, right-click in the threads pane, and then click Make current.
View the data members of a process
The processes pane lists all the processes that are currently running in the BlackBerry Integrated Development Environment. You can expand each process to view its data members. The Process column displays each process in the format: process_name(process_id). > To view data members, in the Process column, expand a process.

View the call stack

The call stack pane displays the calling methods at the current point of execution.
View the source code of a calling method
1. Right-click a method. 2. Click Show Definition. The source file appears in the Edit window at the line of code that implements the class of the selected item. All BlackBerry Integrated Development Environment panes update to reflect the new context.
Note: The first calling method that appears in the call stack pane is located at the bottom of the call stack.

View event logs

The event log pane displays all exception messages that the BlackBerry Integrated Development Environment produces when you run a BlackBerry Java Application in the BlackBerry Device Simulator or on a BlackBerry device. To identify an error that has occurred, use the event log pane to view the source code that caused the error message.
View the source of a logging message
> In the event log pane, on the Build tab, double-click the error message.

View classes

Select a subset of classes
Type the Class Name Prefix and press ENTER. For example, type java.lang. In the classes pane, classes that start with the string typed in the Class Name Prefix field appear. 1. In the classes pane, right-click a class. 2. Perform one of the following tasks:
Step Click Source code. Click Break when exception thrown. Click Break on new object. Task > > > Display the source code that implements the selected class. Set the BlackBerry Integrated Development Environment to trigger a breakpoint when the code throws an object of the selected class. Set the BlackBerry IDE to trigger a breakpoint when an object of the selected class is instantiated.

SigKey: The name of each signature key (.csi) file. Use the following naming conventions for the keys: client-RRT-*.csi, client-RBB-*.csi, client-RCR-*.csi. Dhttp.proxyHost: The name or IP address of the proxy server. Dhttp.proxyPort: The proxy server port number if you do not specify 80 as the default port number. 3. Repeat step 2 for each.csi file that you want to register. Sign a BlackBerry Java Application using a proxy server. 1. At the command prompt, browse to the BlackBerry Signature Tool bin directory. For example:
Java -jar -Dhttp.proxyHost=myproxy.com -Dhttp.proxyPort=80 SignatureTool.jar
3. In the File Selection window, select the.cod file(s) to sign. 4. Click Open.
Request a replacement registration key
Your registration key and.csk file are stored together. If you lose the registration key or the.csk file, you cannot request code signatures. > > If you are an ISV partner and lose the.csk file, contact your ISV Technical Partnership Manager. If you are not an ISV partner, send an email message to jde@rim.com.

View signature status

1. Start the BlackBerry Signature Tool. 2. Select a.cod file. 3. View the Status column: For files the Web Signer has signed, the Status column contains Signed. For files the Web Signer did not sign, the Status column contains Failed. The Web Signer might have rejected the.cod file because the private key password was typed incorrectly.
Distributing BlackBerry Java Applications over the wireless network
Method User-initiated wireless pull Description Developers can post their compiled BlackBerry Java Applications to a public or private web site, and BlackBerry device users can download the BlackBerry Java Application over the wireless network by pointing the web browser on their BlackBerry devices to this URL. When a BlackBerry device user visits the URL, the browser prompts the BlackBerry device user to install the BlackBerry Java Application. If the BlackBerry device user accepts, the BlackBerry Java Application downloads over the wireless connection and installs immediately. In an enterprise environment, the BlackBerry Enterprise Server administrator can push BlackBerry Java Applications out to BlackBerry device users over the wireless network and enforce that the BlackBerry Java Application installs. The administrator simply creates a new policy and indicates that the BlackBerry Java Application is required. Once the policy is set on the BlackBerry Enterprise Server, the BlackBerry Java Application is sent to the BlackBerry device users without the need for any actions on the part of the BlackBerry device users. See the BlackBerry Enterprise Server for Microsoft Exchange System Administration Guide for more information about pushing BlackBerry Java Applications to a BlackBerry device over the wireless network.

deliver-after-timestamp

XML control entity attributes
X-Wap-Application-Id push-id
Example / 123@wapforum.org
ppg-notify-requested-to deliver-before-timestamp
http://wapforum:8080/ ReceivePAPNotification 2004-01-20T22:35:00z
Specify the date and time after which content is delivered to the BlackBerry device. Content is not delivered before this date. Represent the date and time in UTC format.

2004-01-20T21:35:00z

address-value Specify the address of the BlackBerry device that the push content is sent to. The destination is the destination internet messaging address or PIN.
WAPPUSH=destination%3AportI/ TYPE=USER@blackberry.com confirmed; unconfirmed
Specify the delivery reliability mode of the content, transport- delivery-method level, or application-level.
For more information about writing server-side push applications using PAP, see the Push Access Protocol (WAP247-PAP-20010429-a) specification at http://www.wmlclub.com. See the PAP 2.0 DTD for information about the WAP Push DTDs.

Appendix:.alx files

Elements in BlackBerry application.alx files

Element

application

Attributes

Description The application element contains the elements for a single BlackBerry Java Application. The application element can also contain additional nested application elements. Nesting lets you require that, when a BlackBerry Java Application loads onto the BlackBerry device, its prerequisite modules also load onto the BlackBerry device. The id attribute specifies a unique identifier for the BlackBerry Java Application. To provide uniqueness, use an ID that includes your company domain in reverse order. For example, com.rim.samples.docs.helloworld.
copyright description directory
The copyright element provides copyright information, which appears in the Application Loader. The description element provides a brief description of the BlackBerry Java Application, which appears in the Application Loader. The directory element provides the location of a set of files. The directory element is optional. If you do not specify a directory, the files must exist in the same location as the.alx file. The directory element specifies the directory relative to the location of the.alx file. Directory elements are cumulative within a BlackBerry Java Application. For example: <application id="com.abc.my.app"> <directory>MyCodFiles</directory> <fileset Java="1.0"> <files> a.cod //resolves to <.alx location>\MyCodFiles b.cod </files> </fileset> <directory>MyCodFiles</directory> <fileset Java="1.0"> <files> c.cod //resolves to <.alx location>\MyCodFiles\MyCodFiles d.cod </files> </fileset> </application>

The BlackBerry IDE includes a full suite of editing and debugging tools that are optimized for the development of a BlackBerry Java Application. TheBlackBerry Smartphone Simulator provides a complete Windows type environment, and is designed to simulate UIs and user interaction, network connections, email services, and wireless data synchronization.
Java ME and Java APIs for BlackBerry
The BlackBerry Java Development Environment Component Package includes the following development tools for development within third-party IDEs such as NetBeans or Eclipse: RAPC: You can use this command prompt compiler to compile.java and.jar files into.cod files that you can run in the BlackBerry Smartphone Simulator or on a BlackBerry device. JavaLoader: You can use this tool to add or update an application on a BlackBerry device for testing, and to view information about application.cod files. BlackBerry Signature Tool: You can use this tool to send code signature requests to the BlackBerry Signing Authority Tool. Preverify Tool: You can use this tool to partially verify your classes before you load your application onto a BlackBerry device. JDWP: You can use this tool to debug applications using third-party integrated development environments.
Java ME is an industry standard platform that defines common sets of Java APIs for different types of wireless and embedded devices. A Java ME application on a BlackBerry device runs in the BlackBerry Java Virtual Machine, which provides all of the runtime services to the applications and performs functions such as typical memory allocations, security checks, and garbage collection. The Java ME MIDP standard addresses the API and BlackBerry JVM needs of a constrained wireless device with a user interface. The BlackBerry device supports the Java ME MIDP standard as defined in JSR 118. The Java MEMIDP standard provides a core set of Java APIs that any BlackBerry device can support, regardless of its underlying operating system. Developers can often build one Java application using the MIDP standard APIs and run that application on many different types of devices.
Support for standard Java APIs
The BlackBerry device and the BlackBerry Java Development Environment support the Java ME MIDP standard, which provides a core set of Java APIs that you can use to develop wireless device applications. The BlackBerry device and the BlackBerry Java Development Environment also support the following JSRs: JSR 30: Connected Limited Device Configuration Version 1.0 (supported on devices with BlackBerry Device Software version 4.0 or earlier) JSR 37: Mobile Information Device Profile Version 1.0 (supported on devices with BlackBerry Device Software Version 4.0 or earlier) JSR 75: Portable Optional Packages for the J2ME Platform (PDAP) support for the PIM APIs only and the File Connection API for Java ME (supported on devices with BlackBerry Device Software version 4.2 or later) JSR 82: Java APIs for Bluetooth JSR 118: Mobile Information Device Profile Version 2.0 JSR 120: Wireless Messaging API (WMA) Version 1.1 JSR 135: Mobile Media APIs (MM API) Version 1.1

BlackBerry solutions

JSR 139: Connected Limited Device Configuration Version 1.1 JSR 172: J2ME Web Services JSR 177: Security and Trust Services API for J2ME (SATSA) JSR 179: Location API for Java ME JSR 185: Java Technology for the Wireless Industry (JTWI) JSR 205: Wireless Messaging API 2.0 JSR 211: Content Handler API JSR 226: Scalable 2D Vector Graphics API for Java ME JSR 238: Mobile Internationalization API
Support for Java API extensions
BlackBerry devices support the following Java APIs that are not part of the standard JSR definitions and that can provide greater features and functionality over what is available in the standard MIDP API libraries. API User Interface APIs Persistent Data Storage APIs Networking and I/O APIs Event Listeners Application Integration APIs Additional Utilities Description You can use these APIs to create screens, menu items, and all the components of the user interface. You can use these APIs to store custom data locally within your application. You can use these APIs to establish network connections and read or write data to a server-side application. You can use the Event Listeners to respond to BlackBerry device user or systeminitiated events on a BlackBerry device. You can use these APIs to integrate with the existing BlackBerry email, phone, calendar, contacts, browser, camera, media player, and task list applications. You can use these additional APIs for data encryption and compression, XML parsing, Bluetooth connectivity, location-based services, and so on.
BlackBerry device users might use either the BlackBerry Enterprise Server or the BlackBerry Internet Service, or they can use both on the same device. Understanding the differences between theBlackBerry Enterprise Server and the BlackBerry Internet Service, and which types of users you plan to support, is important, as it might impact which modes of transport you use and how you manage data synchronization.
BlackBerry Enterprise Solution
The BlackBerry Enterprise Server is part of the BlackBerry Enterprise Solution. The BlackBerry Enterprise Server exists behind the corporate firewall and provides a wireless gateway for BlackBerry device users in an organization to access corporate email and organizer data. The BlackBerry Enterprise Server also provides the following key features: data encryption and compression BlackBerry device management and monitoring utilities simplified application provisioning authenticated gateway for intranet access from a BlackBerry Java Application

Avoiding java.util.Enumeration
Avoid using java.util.Enumeration objects unless you want to hide data (in other words, to return an enumeration of the data instead of the data itself). Asking a vector or hash table for an Enumeration object is slow and creates unnecessary garbage. If another thread might modify the vector, synchronize the iteration. The Java SE uses an Iterator object for similar operations, but Iterator objects are not available in the Java ME. Code sample for( int i = v.size() - 1; i >=0; --i ) { o = v.elementAt( i );. } synchronized( v ) { for( int i = v.size() - 1; i >=0; --i ) { o = v.elementAt( i );. } }
Performing casts using instanceof
Use instanceof to evaluate whether a cast succeeds. Code sample if( x instanceof String ) { (String)x.whatever(); } else {. } x
Evaluating conditions using instanceof
To produce smaller and faster code, if you evaluate a condition using instanceof, do not evaluate explicitly whether the variable is null. Code sample if( e instanceof ExampleClass ) {. } if( ! ( e instanceof ExampleClass ) ) {. }
Avoiding StringBuffer.append (StringBuffer)
To append a String buffer to another, a BlackBerry Java Application should use net.rim.device.api.util.StringUtilities.append ( StringBuffer dst, StringBuffer src[, int offset, int length ] ). Code sample public synchronized StringBuffer append(Object obj) { if (obj instanceof StringBuffer) { StringBuffer sb = (StringBuffer)obj; net.rim.device.api.util.StringUtilities.append( this, sb, 0, sb ) return this; } return append(String.valueOf(obj)); }

Avoiding returning null

If you write a public method that returns an object, the method should return null only under the following conditions: Your application expects a null value to occur during normal application operation. The Javadoc @return parameter for the method states that null is a possible return value.
If your application does not expect a null return value, the method should throw an appropriate exception, which forces the caller of the method to deal explicitly with the problem. The caller of the method might not need to check for a null return value unless the caller of the method throws a null exception.
Avoiding passing null into methods
Do not pass null parameters into an API method unless the API Reference states explicitly that the method supports them.
Using caution when passing null into a constructor
To avoid ambiguity when passing null into a constructor, cast null to the appropriate object. If a class has two or more constructors, passing in a null parameter might not uniquely identify which constructor to use. As a result, the compiler reports an error. By casting null to the appropriate object, you indicate precisely which constructor the compiler should use. This practice also provides forward compatibility if later releases of the API add new constructors. Code sample

Avoiding unnecessary field initialization
Where possible, allow fields to initialize automatically as follows: object references are initialized to null int, byte, or long is initialized to 0 Boolean is initialized to false
You must explicitly initialize local variables in a method.

Multilanguage support

Code sample class BetterExample { private int fieldsCount; private Field _fieldWithFocus; private boolean _validLayout; private boolean _validLayout; }
Importing individual classes
A BlackBerry Java Application that uses only a small number of classes from a package should only import the individual classes. Code sample import net.rim.blackberry.api.browser.Browser;
The BlackBerry Integrated Development Environment includes a resource mechanism for creating string resources. The Localization API is part of the net.rim.device.api.i18n package. MIDP applications do not support localization. TheBlackBerry Integrated Development Environment stores resources for a locale in a ResourceBundle object. A ResourceBundleFamily object contains a collection of ResourceBundles, which groups the resources for an application. The application can switch languages, depending on the locale of the BlackBerry device user, without requiring new resource bundles. You can use the BlackBerry Integrated Development Environment to compile each resource bundle into a separately compiled.cod file. You can load the appropriate.cod files onto BlackBerry devices with the other.cod files for the application. Resources are organized in a hierarchy based on inheritance. If a string is not defined in a locale, a string from the next closest locale is used.
Best practice: Storing text strings in resource files
Instead of using text in source code, design applications to use resource files for localization (adapt to specific languages and regions). Consider the following guidelines: Store the text strings for each locale in a single resource file. In your source code, use unique identifiers to make use of the appropriate resource files. Design the application to dynamically retrieve the appropriate resource file to display to the BlackBerry device user based on the locale of the BlackBerry device user.

Multimedia support

Audio support

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

Imaging support

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

Video support

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

UI and navigation design

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

Trackball sensitivity

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

You can use the BlackBerry UI APIs to create UIs that include tables, grids, and other specialized features. The BlackBerry Java Development Environment uses a standard Java event model to receive and respond to specific types of events. Applications can receive and respond to BlackBerry device user events, such as when the BlackBerry device user clicks the trackwheel, clicks the trackball, or types on the keyboard, and to system events, such as global alerts, real-time clock changes, and USB port connections.

Memory management

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

BlackBerry device memory

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

Key resources to reserve

Flash memory: The persistent storage space that is available on the BlackBerry device is a fixed amount of flash memory, typically in the range of 8 MB to 64 MB. Persistent object handles: The handles that are assigned to each persistent object are consumed only by persistent objects. The amount of flash memory on the BlackBerry device determines the fixed number of persistent object handles in the system. Object handles: Each object and array of primitives has an object handle associated with it. The amount of flash memory on the BlackBerry device determines the fixed number of object handles in the system.

Managing low memory availability
Best practice: Minimizing memory use
To minimize runtime memory, consider the following guidelines: Use primitive types (such as int or Boolean) instead of objects (such as String or Integer). Do not depend entirely on the garbage collector. Avoid creating many objects quickly. Set object references to null when you are finished using them. Reuse objects as much as possible. Move heavy processing to the server. For example, you can filter or sort data before sending it to the BlackBerry device.
The low memory manager handles memory resources on the BlackBerry device when the available memory resources fall below a certain threshold. The low memory manager attempts to free used memory to provide more available memory on the BlackBerry device. All applications, including BlackBerry Java Applications, should work with the low memory manager to free as much memory as possible when the BlackBerry device is low on memory resources.
Identifying low memory availability on a BlackBerry device
The following conditions can cause the low memory manager to attempt to free memory resources: The amount of available flash memory on the BlackBerry device falls below a certain threshold. The flash memory threshold depends on the amount of free RAM in the system. The flash memory threshold ranges between 400 KB and 800 KB. The number of persistent object handles that are available on the BlackBerry device falls below 1000 persistent object handles. The number of object handles that are available on the BlackBerry device falls below 1000 object handles.

Conserving resources

Best practice: Using efficient data structure selection
Data structure selection defines how many object handles and how much flash memory a BlackBerry Java Application consumes. Improper data structure selection can consume key resources without improving the BlackBerry Java Application functionality or the BlackBerry device user experience. Consider the following guidelines:
The data structure should consist of the minimum possible number of objects, especially when you use high-level objects like a Vector or a Hashtable. These classes provide significant functionality but are not efficient storage mechanisms and you should avoid using them in the persistent store if possible. When possible, use primitives instead of objects, because primitives reduce the number of object handles that are consumed on the BlackBerry device. An array of primitives is an object and consumes an object handle. String objects are as efficient as byte arrays. A String object consumes only one object handle and is equivalent if your application stores all of the characters as a byte. In other words, the value of each character is less than or equal to the decimal value of 255. If your application cannot store characters as a byte, you can store the characters as a String because it is equivalent to storing a char array.

device user must manually execute the synchronization by running the BlackBerry Desktop Manager add-in, which notifies the application on the BlackBerry device to send the data to the computer application. You can also write data to the computer application using the native USB protocols.

Wireless data transport

Wireless gateways
Java applications for BlackBerry devices can use standard HTTP, HTTPS, and TCP socket protocols to establish connections over the wireless network. When an application establishes a connection over the wireless network, it can use one of two wireless gateways to proxy the connection to the Internet or to the corporate intranet. You can design your application to rely on the default gateway that is available to the BlackBerry device user, or you can customize your code to choose a preferred gateway. Design your application to explicitly choose the preferred gateway for the connection and use the default gateway if the preferred method is not available. This might minimize the number of network connection issues that your customers face and let your application use a consistent connectivity model across all network types and wireless operators.
Using the BlackBerry Enterprise Server as an network gateway
When you use the BlackBerry Enterprise Server as a network gateway, all traffic between your application and the BlackBerry Enterprise Server is encrypted using AES or triple DES encryption. Because the BlackBerry Enterprise Server is located behind the organization's firewall and provides inherent data encryption, applications can communicate with application servers and web servers that are located on the organization's intranet. The BlackBerry Mobile Data System component of the BlackBerry Enterprise Server includes the BlackBerry MDS Services, which provides an HTTP and TCP/IP proxy service to allow the BlackBerry Java Application to use it as a secure gateway for managing HTTP and TCP/IP connections to the intranet. If your application connects to the Internet, you might be able to use the BlackBerry Enterprise Server as a gateway. Network requests travel behind the organization's firewall to the BlackBerry Enterprise Server, which makes the network request to the Internet through the corporate firewall. Administrators can set an IT policy to make sure that the BlackBerry Enterprise Server is the gateway for all wireless network traffic, including traffic destined for the Internet. If your application connects to the Internet, you can also use either the BlackBerry Internet Service or the Internet gateway of the wireless server provider to manage connections.
Using the wireless service provider's Internet gateway
Most wireless service providers provide an Internet gateway that offers direct TCP/IP connectivity to the Internet. Some wireless service providers also provide a WAP gateway that allows HTTP connections to occur over the WAP protocol. A BlackBerry Java Application can use either of these gateways to connect to the Internet. If your application is for BlackBerry device users who are on a specific wireless network, using the wireless service provider's Internet gateway can often yield good results. If your application is for BlackBerry device users on a variety of wireless networks, testing your application against the different Internet gateways and achieving a consistent and reliable experience can be challenging. You might find it useful to use the BlackBerry Internet Service, and use the wireless service providers Internet gateway as a default connection type if the BlackBerry Internet Service is not available.

Alternative data transport options
Using email to transport data
You can use the BlackBerry APIs to create aBlackBerry Java Application that uses email as a transport mechanism for sending and receiving data. Email can be an effective way to proactively distribute content to BlackBerry device users if the traditional push models are not available. A BlackBerry Java Application can use the BlackBerry APIs to send email messages and listen for inbound email messages. A BlackBerry Java Application can also access the details and headers of email messages that are stored locally on the BlackBerry device and register listeners for changes in the status of an email message.
Using SMS to transport data
You can use the BlackBerry APIs to create applications that use SMS as a transport mechanism for sending and receiving data. The BlackBerry APIs allow an application to send SMS messages and listen for inbound SMS messages.
Using PIN messaging to transport data
PIN messaging uses the data channel rather than the voice channel and allows you to address the destination BlackBerry device by its unique PIN number. PIN messaging can only be used to send data from one BlackBerry device to another. The BlackBerry APIs can also allow an application to programmatically send and receive BlackBerry PIN messages. PIN messaging can be an effective way to implement PIN applications targeting BlackBerry device users only.
BlackBerry application integration

Adding custom menu items

A BlackBerry Java Application can add custom menu items to the menu on the BlackBerry device for the email, organizer, and phone applications. When a BlackBerry device user selects the custom menu item, theBlackBerry Java Application starts with a reference to the object that the BlackBerry device user selects. For example, a BlackBerry Java Application can add a menu item called Show Location of Sender to the email application. When the BlackBerry device user selects the menu item, the BlackBerry Java Application starts with a reference to the email object that is currently highlighted or that the user opens. The BlackBerry Java Application uses the email address of the sender to determine the location of the sender by retrieving the email address from the contact list, or by retrieving data from a remote server, and then comes to the foreground and displays a map.

Security considerations

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

Access to memory

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

Authentication

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

Test a BlackBerry Java Application
Obfuscating a BlackBerry Java Application
The compiler for the BlackBerry Java Development Environment and the BlackBerry JDE Plug-in for Eclipse is set to minimize the size of the application. The compiler produces a.cod file that provides obfuscation-like services that are similar to those that obfuscation packages provide in an effort to reduce the size of the.cod file. For example, the BlackBerry Java Development Environment removes the following information from a.cod file: all debug information local variable names source line numbers private method and member names
It is not typically necessary for you to provide obfuscation for your applications in addition to the existing obfuscation that, by default, the BlackBerry JDE provides. In fact, Research In Motion does not perform any additional obfuscation of its own products. The BlackBerry JDE does not integrate support for obfuscation through third-party tools. You must include a command-line procedure to obfuscate.cod files for use on BlackBerry devices.
Preverifying a BlackBerry Java Application
When you preverify your classes, you reduce the amount of processing that the BlackBerry device must perform when you install your application. To partially verify your classes before you install your application on a BlackBerry device, you can use the Preverify tool, available with the BlackBerry Java Development Environment. You can use the BlackBerry Smartphone Simulator to preverify the.cod files. For more information about using the BlackBerry Smartphone Simulator, see the BlackBerry Device Simulator User Guide. For more information about using the Preverify tool, see the BlackBerry Java Development Environment Development Guide.
Testing applications on a BlackBerry Smartphone Simulator
After you develop and compile your application, you can test it on the BlackBerry device. The most common first step is to set the BlackBerry Java Development Environment to use a BlackBerry Smartphone Simulator. The BlackBerry Smartphone Simulator runs the same Java code as the BlackBerry devices, so the BlackBerry Smartphone Simulator provides an accurate environment for testing how applications will function on a BlackBerry device. The BlackBerry JDE includes current versions of the BlackBerry Smartphone Simulator. To download additional versions of the BlackBerry Smartphone Simulator, visit www.blackberry.com/developers/index.shtml.

Testing applications on a BlackBerry device
After you test your application on the BlackBerry Smartphone Simulator, you can install your application on a BlackBerry device. If your application uses signed APIs, you might need code signing keys. After you install the application on the BlackBerry device, you can open the application and test its functionality and performance. For debugging purposes, you can attach your device to the BlackBerry Integrated Development Environment and use the debugging tool to step through your application code. The BlackBerry IDE can be useful if you are trying to identify a network or Bluetooth issue, or other issues that are difficult to simulate.

BlackBerry simulators

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

BlackBerry MDS Simulator

The BlackBerry MDS Simulator is designed to simulate the BlackBerry MDS Connection Service component of the BlackBerry Enterprise Server. When you use the BlackBerry Smartphone Simulator with the BlackBerry MDS Simulator you can test network, push HTTP, and browser applications that are designed for use with a BlackBerry Enterprise Server. To get the BlackBerry MDS Simulator, visit www.blackberry.com/developers and download the BlackBerry Email and MDS Services Simulator Package.