Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT Instruction Manual

©2008 Research In Motion Limited. All rights reserved.www.blackberry.com
BlackBerry Java Development
Environment
version 4.7.0
Release Notes and Known Issues List

2 of 8
©2008 Research In Motion Limited. All rights reserved.www.blackberry.com
NOTE
This document is provided for informational purposes only, and does not constitute a binding legal
document unless specifically incorporated by reference into a binding legal agreement between you and
Research In Motion (RIM). In the event that you enter into a binding legal agreement with RIM, all
provisions contained in such binding legal agreement shall apply, regardless of whether such provisions
conflict with information contained herein.
©2008 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, “Always On, Always Connected” and the “envelope in motion” symbol are registered with the
U.S. Patent and Trademark Office and may be pending or registered in other countries.
Java and J2ME are registered trademarks of Sun Microsystems, Inc. Microsoft Vista, DirectX, and Windows
are trademarks of Microsoft Corporation. Intel and Pentium are trademarks of Intel Corporation. Bluetooth is
a trademark of Bluetooth SIG. All other brands, product names, company names, trademarks and service
marks are the properties of their respective owners.
The BlackBerry device 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; D445,428; D433,460; D416,256. Other patents are registered or pending in various
countries around the world. Visit www.rim.com/patents.shtml for a current list of RIM [as hereinafter defined]
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 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.
Send us your comments on release notes and known issues lists:
https://www.blackberry.com/DocsFeedback.
19172670

3 of 8
©2008 Research In Motion Limited. All rights reserved.www.blackberry.com
About the BlackBerry JDE
The BlackBerry® Java® Development Environment is a fully integrated development environment and
simulation tool for building Java 2 Platform, Micro Edition applications for Java-based BlackBerry® devices.
It is a Mobile Information Device Profile (MIDP) compliant J2ME™ environment for developers who wish to
maintain seamless portability in their wireless applications.
Use the BlackBerry JDE to build applications that take advantage of the unique features of the BlackBerry
device, such as desktop synchronization applications, GPS applications, and applications that push content
proactively to BlackBerry devices in environments that use the BlackBerry Enterprise Server. The
BlackBerry JDE provides ways for BlackBerry device applications to establish network connections to
servers on the Internet or the corporate intranet.
Each version of the BlackBerry JDE comes with the BlackBerry Smartphone Simulators that were available
when that version of the BlackBerry JDE was made public. You can download additional BlackBerry
Smartphone Simulators from the BlackBerry Developer Zone web site:
http://www.blackberry.com/developers/index.shtml.
Getting started with the BlackBerry JDE
You can start the BlackBerry® Java Development Environment in one of two ways:
1. From the Start menu, select:
Programs > Research In Motion > BlackBerry JDE 4.7.0 > JDE
2. Invoke ide.bat, located in the bin subdirectory of the BlackBerry JDE installation directory.
Internationalization
The BlackBerry® Java Development Environment contains tools that assist with internationalization (i18n)
efforts. It is important to follow naming conventions.
Note: The .rrc and .rrh files must exist in the same directory for successful compilation.
Note: You should define resource keys in uppercase letters only.
See the BlackBerry Java Development Environment Development Guide or the BlackBerry Integrated
Development Environment Online Help for more information about localization.
Code samples
A sample BlackBerry® JDE workspace exists in the samples subdirectory of the BlackBerry JDE installation
directory. It contains sample programs that demonstrate how to design and build Java applications for
BlackBerry devices
Code samples with server components
The following sample applications include server components. Invoke the run.bat script in the specified
folder to start the server component:
•3.1 The httppushdemo sample includes a server component at
samples/com/rim/samples/server/httppushdemo

4 of 8
©2008 Research In Motion Limited. All rights reserved.www.blackberry.com
•3.2 The socketdemo sample includes a server component at
samples/com/rim/samples/server/socketdemo
•3.3 The browserpushdemo sample includes a server component at
samples/com/rim/samples/server/browserpushdemo
•3.4 The smsdemo sample includes a server component at
samples/com/rim/samples/server/smsdemo
•3.5 The BrowserMultipartPushDemo sample includes a server component at
samples/com/rim/samples/server/browsermultipartpushdemo
•3.6 The GPS Demo sample includes a server component at
samples/com/rim/samples/server/gpsdemo
BlackBerry Smartphone simulators
This release of the BlackBerry® Java™ Development Environment includes the following BlackBerry
Smartphone simulator(s):
Storm Smartphone simulator
BlackBerry JDE version 4.7.0 system requirements
Your system must meet the following requirements to support the BlackBerry® Java™ Development
Environment:
•Microsoft® Vista™ or Windows XP
•Intel® Pentium® III processor or compatible (800 MHz or higher)
•256 MB RAM
•500 MB free hard disk space
•Java® SE Development Kit (JDK) version 5 or version 6 (download from the Sun Microsystems
web site). The <bin> directory of the Java SDK must be part of the system's PATH variable.
•Java® SE Development Kit (JDK) version 6 is required for the BlackBerry MDS Simulator version
4.1.5.
•Microsoft DirectX® 8.0 or greater (for the BlackBerry Smartphone Simulators)
Functional changes
This section lists functional changes for BlackBerry® Java Development Environment (JDE) version 4.7.0.
Determine if a
BlackBerry device
application is in
touch compatibility
mode.
A BlackBerry® device application created in the BlackBerry JDE version 4.7.0 and on a
BlackBerry® Storm device responds to touch events and touch gestures.
A BlackBerry device application created in the BlackBerry JDE version 4.6.0 or earlier and
on a BlackBerry Storm device runs in compatibility mode and does not respond to touch
events or touch gestures.
You can determine if a BlackBerry device application is in compatibility mode by invoking
net.rim.device.api.system.Application.isInTouchCompatibilityMode().
Set a BlackBerry
device application You can set a BlackBerry® device application created in the BlackBerry Java Development Environment version 4.6.0 or earlier to automatically respond to touch events

5 of 8
©2008 Research In Motion Limited. All rights reserved.www.blackberry.com
to respond to touch
events and
gestures on the
BlackBerry Storm
device.
and touch gestures when the application starts.
In the .jad file for a BlackBerry device application, set the the RIM-
TouchCompatibilityMode property to 'false'.
Allow a user to set
the run mode for a
BlackBerry device
application on the
BlackBerry Storm
device.
You can allow a BlackBerry® device user to manually set a BlackBerry device application
to run in compatibility mode. The BlackBerry device user sets the mode through the
Options screen on the BlackBerry device.
In the .jad file for a BlackBerry device application, set the the RIM-
TouchCompatibilityMode-UserChangeable property to '’true'.
Allow a BlackBerry
device application
to respond to touch
screen input.
A BlackBerry® device application can use the net.rim.device.api.ui.TouchEvent
class, the net.rim.device.api.ui.TouchGesture class, or both to support and
respond to touch screen input events such as taps, swipes, and gestures from a
BlackBerry device user.
Allow a MIDlet to
respond to touch
screen input.
A MIDlet can override the Canvas.pointerPressed(),
Canvas.pointerReleased(), and Canvas.pointerDragged() methods to respond
to touch screen input events.
A MIDlet can also override the public void touchEvent(TouchEvent message)
method in any of the BlackBerry® specific MIDP classes: BlackBerryCanvas,
BlackBerryGameCanvas and BlackBerryCustomItem,to respond to touch screen
input events.
Use the touch
screen keyboard. A BlackBerry® device application can use the
net.rim.device.api.ui.container.MainScreen.getVirtualKeyboard()
method with the methods of the net.rim.device.api.ui.VirtualKeyboard class to
display or hide the touch screen keyboard.
Use the touch screen keyboard APIs to allow a BlackBerry device application to make the
touch screen keyboard available to BlackBerry device users when they wish to provide
keyboard input.
Work with screen
orientation. A BlackBerry® device application can use the
net.rim.device.api.ui.Display.getOrientation() method to retrieve the
orientation of the screen. A BlackBerry device application can also use the
net.rim.device.api.ui.UiEngineInstance.setAcceptableDirections(byte
flags) method to set the screen direction that the application supports.
Respond to the
orientation of the
BlackBerry device.
A BlackBerry® device application can use the
net.rim.device.api.system.AccelerometerSensor class to retrieve information
from the accelerometer of a BlackBerry device. Use the AccelerometerSensor class to
allow a BlackBerry device application to respond to changes in the orientation of the
BlackBerry device.
Setting the
background image
of the Home
screen.
A BlackBerry® application can invoke net.rim.blackberry.api.homescreen
HomeScreen.setBackgroundImage(String uri) to set the background image of
the Home screen on a BlackBerry smartphone. The image file must be located in the flash
memory of the BlackBerry smartphone or the microSD card. For example, uri =
"file:///store/home/user/pictures/file.jpg".
Sending and
handling a camera
image.
A BlackBerry® application can now register to handle images that a BlackBerry
smartphone user sends from the camera application. After registration, when a BlackBerry
Smartphone user takes a picture, a menu item appears in the menu of the camera
application that allows a user to send an image to the BlackBerry application.
Invoking the video
A
BlackBerr
y
® application can invoke net.rim.blackberry.api.invoke.
Invoke.invokeApplication(Invoke.APP_TYPE_CAMERA,new

6 of 8
©2008 Research In Motion Limited. All rights reserved.www.blackberry.com
recorder. CameraArguments(CameraArguments.ARG_VIDEO_RECORDER) to start the video
recorder application.
Audio and video
support on the
BlackBerry Storm
device.
The BlackBerry® Storm device supports audio recording and the playback of audio and
video.
Support for audio recording
•GSM 6.10
•QCELP
•AMR-NB
Support for audio playback
•PCM, uLaw/aLaw and GSM 6.10 in WAV format
•AAC/AAC+/eAAC+ in M4A and AAC formats
•MP3
•MIDI
•WMA
•AMR-NB
Support for Video playback
•MPEG 4-SP in an AVI format
•MPEG 4-SP and H.263 in MP4, 3GP and MOV formats
•WMV
Displaying the
music library in the
media player.
A BlackBerry® device application can use the
javax.microedition.content.Invocation class and the
net.rim.device.api.content.BlackBerryContentHandler class to start the
media application and view the music library.
For example:
Invocation invocation = new Invocation();
invocation.setID( BlackBerryContentHandler.ID_MEDIA_CONTENT_HANDLER
); invocation.setArgs( new String[]
{BlackBerryContentHandler.MEDIA_ARGUMENT_VIEW_MUSIC} );
Registry.invoke( invocation );
Launching a
BlackBerry device
application from the
Music player or the
Music library
Screen.
A BlackBerry® device application can use the
net.rim.blackberry.api.menuitem.ApplicationMenuItem and
net.rim.blackberry.api.menuitem.ApplicationMenuItemRepository
classes to add links to the music player and the music library. A BlackBerry device user
can select the links to launch the BlackBerry device application.
For example:
ApplicationMenuItemRepository repository =
ApplicationMenuItemRepository.getInstance();
repository.addMenuItem(
ApplicationMenuItemRepository.MENUITEM_MUSIC_SERVICE_LIST_ITEM, new
MusicServiceListItem());
Retrieve the
browser user
agent.
A BlackBerry® device application can invoke
java.lang.System.getProperty(“browser.useragent”) to retrieve the browser
user agent from the Browser.
BlackBerry Storm On the BlackBerry® Storm device, the content store memory that a BlackBerry device

7 of 8
©2008 Research In Motion Limited. All rights reserved.www.blackberry.com
device memory. application accesses through the File Connection API has no limit for individual file sizes.
Default menu now
includes system
menu items.
The default menu for an application Screen now includes system menu items.
Known issues
This section lists known issues for the BlackBerry Java Development Environment (JDE) version 4.7.0.
APIs
Receiving event
notification from a
Player
A BlackBerry® device application that uses a
javax.microedition.media.PlayerListener for a
javax.microedition.media.Player does not receive events until the
javax.microedition.media.Player is in the STARTED state.
Impact: A BlackBerry device application may not be notified of certain
javax.microedition.media.Player events.
Workaround: To begin receiving events from the
javax.microedition.media.Player, put the
javax.microedition.media.Player in to the STARTED state.
Using the
Accessibility APIs The BlackBerry ® JDE version 4.7.0 does not support the Accessibility APIs. If you run
an application that uses the Accessibility APIs on the BlackBerry Storm device or in the
simulator for the BlackBerry® Storm device, an UnsupportedOperationException
is thrown.
BlackBerry
Storm simulator
Performing a
scrolling action. On the simulator for the BlackBerry® Storm device, scroll actions may not work as
expected.
Impact: You may not be able to perform scroll actions on the simulator for the
BlackBerry Storm device.
Workaround: Use the arrow keys on the computer keyboard to scroll in the Home
screen.
Simulating device
rotation in the
BlackBerry Storm
simulator
On the simulator for the BlackBerry® Storm device, when you simulate a rotation, the
following methods return data for the previous orientation:
•Channel.getLastAccelerationData(short[])
•AccelerometerData.getLastXAcceleration()
•AccelerometerData.getLastYAcceleration()
•AccelerometerData.getLastZAcceleration()
•AccelerometerData.getXAccHistory()
•AccelerometerData.getYAccHistory()
•AccelerometerData.getZAccHistory()
Impact: When you simulate a rotation, incorrect orientation readings will result.
Workaround: On the simulator for the BlackBerry Storm device, simulate the same
orientation or rotation event twice in a row.
Running the maps
sample application On the simulator for the BlackBerry® Storm device, if you run the BlackBerryMapsDemo
sample application, the BlackBerry Smartphone Simulator displays an error message if

8 of 8
©2008 Research In Motion Limited. All rights reserved.www.blackberry.com
you select the following options from the application menu:
•Invoke Location Document > View Single Location > View Map
•Invoke Location Document > View Multiple Locations > View Map
•Invoke Location Document > View Route > View Map
•Invoke Map View > View Map
Impact: You cannot view a map for a single location, multiple locations, a route, or view
a map using map view.
Workaround: None.
Running the
camera sample
application
On the simulator for the BlackBerry® Storm device, if you run the CameraDemo sample
application, the BlackBerry Smartphone Simulator displays an error message and stops
functioning.
Impact: You cannot successfully run the CameraDemo sample application on the
BlackBerry Storm Simulator.
Workaround: None.
Using the virtual
keyboard Screen classes only contain one method for the touch screen keyboard. The
getVirtualKeyboard() method returns a
net.rim.device.api.ui.VirtualKeyboard object that contains methods for
setting and getting the state of the virtual keyboard.
Launching a MIDlet
in the BlackBerry
Storm simulator
On the simulator for the BlackBerry® Storm device, when you launch a MIDlet that uses
commands of type SCREEN, the commands appear as Toolbar buttons on the bottom
of the screen.
Impact: MIDlet commands of type SCREEN display as Toolbar buttons on the screen of
a MIDlet.
Workaround: Commands of type ITEM.
Launching the
menu of a MIDlet On the simulator for the BlackBerry® Storm device, if you set the portrait keyboard to
the 12 key, you cannot open the menu in a MIDlet application.
Impact: You cannot open a menu in a MIDlet application if you have set the 12 key as
the portrait keyboard.
Workaround: Set a different key as the portrait keyboard.