BlackBerry Java SDK 7.0
Send Menu API
You can use the Send Menu API to add a Send menu item to a menu in your app. The Send menu item allows you to send content from your app to a recipient by using another application on the BlackBerry device, such as the Messages application or BlackBerry Messenger. The content to send is encapsulated in a JSONObject object that is passed from your app to the application that sends the content from the device.
When a BlackBerry device user clicks the Send menu item, a submenu is displayed with a list of applications that can be used to send the content. When the user clicks one of these applications, the selected application starts with certain fields populated automatically with the content to send. The user can complete the remaining fields and send the content.
Command framework enhancements
When you register commands with the Command Framework API, you can unregister the commands with unregisterCommand(), unregisterCommandCategory(), or unregisterModuleCommands(). These methods are located in the LocalCommandRegistrarConnection class, which is included in the net.rim.device.api.command package.
For more information about the Command Framework API, see the UI & Navigation Development Guide for the BlackBerry Java SDK.
Layering UI elements
You can place UI components on top of other UI components using the ComponentCanvas class. Unlike AbsoluteFieldManager, which provides similar functionality, a ComponentCanvas is drawn on top of other fields and managers on a screen, like a video or camera field. You can add standard UI components, such as labels, buttons, and drop-down lists, to ComponentCanvas. For example, you can use a ComponentCanvas to display a series of buttons on top of a video field or camera field.
ComponentCanvas is found in the net.rim.device.api.ui.container package.
Scanning an image for barcode data
The ZXing 1.6 barcode scanning library is supported in the com.google.zxing package. The net.rim.device.api.barcodelib package provides helper classes for barcode scanning.
You can use the BarcodeScanner class to scan and decode 1D- or 2D-barcode data from a frame detected by the camera's viewfinder. When you create a new instance of BarcodeScanner, you pass the constructor an instance of a BarcodeDecoder class and an implementation of the BarcodeDecoderListener or ImageDecoderListener interface. Using decode() (contained in the BarcodeDecoder class) you can parse data into either a byte array or Bitmap object, and perform an action based on that data using barcodeDecoded().
Scanning an image for data
You can use the ImageScanner class to scan and decode data from a frame detected by the camera. When you create a new instance of ImageScanner, you pass the constructor both an implementation of the ImageDecoder interface, and the ImageDecoderListener interface.
The ImageDecoderListener interface provides a method, imageDecoded(), which is invoked when the ImageDecoder is finished parsing the image. These classes are provided in the net.rim.device.api.amms.control.camera package.
Retrieving the luminance source of a bitmap
You can use the BitmapLuminanceSource and PlanarYUVLuminanceSource classes to create objects that represent the grayscale profile of a bitmap object. You can find these classes in the net.rim.device.api.barcodelib package.
Lightweight Font object
The FontSpec class, provided in the net.rim.device.ui package, represents a lightweight Font object containing basic Font attributes such as font family, size and style. FontSpec is used in OpenVG API methods such as vgtDrawText(). You can get the FontSpec object representing a Font by using the Font.getFontSpec() method.
Determining supported color quality
You can retrieve the color quality that a BlackBerry device supports by invoking DeviceCapability.getDisplayColorQuality(), which is provided in the net.rim.device.api.system.capability package. This method returns a TRUE_COLOR constant if the device supports 32-bit color. It returns a HIGH_QUALITY constant when the device supports 16-bit color.
Drawing gradient rectangles
You can use the Graphics class in the net.rim.device.api.ui package to draw rectangles with a gradient fill in your application. The gradient fill varies the color within the rectangle based on position, creating a smooth color transition. You can invoke drawGradientFilledRect() to draw a rectangle with a gradient fill with sharp corners, and you can invoke drawGradientFilledRoundedRect() to draw a rectangle with a gradient fill with rounded corners.
32-bit color bitmaps
You can invoke Bitmap.createAlpha() on a Bitmap object to add an alpha transparency channel to the object. The createAlpha() method automatically selects the bitmap format.
Retrieving the bitmap type for a given image frame's alpha channel
You can retrieve the bitmap type for the alpha channel of a given frame using the new getAlphaType() method provided by the net.rim.device.api.system.EncodedImage class.
On some BlackBerry® 7 devices, a magnetometer sensor is integrated into the device (currently, only devices with touch screens have this functionality). The magnetometer sensor detects magnetic fields along the three axes of a BlackBerry device. You can use the Magnetometer APIs that are provided in the net.rim.device.api.system package to create applications (for example, a stud finder or a compass) that detect the XYZ magnetic fields and the Earth's magnetic poles.
Retrieving the inclination or declination of a geomagnetic field
You can retrieve the inclination, declination, and several other estimates for a geomagnetic field with the GeomagneticField class. The GeomagneticField is provided in the net.rim.device.api.location package.
The Compass application uses the Magnetometer APIs to provide the BlackBerry® device user with the direction of the BlackBerry device relative to Earth's magnetic poles. The Compass application integrates with BlackBerry Maps and provides the user with the ability to specify a destination.
Unified search enhancements
A number of enhancements have been made to the Unified Search Service.
The SearchableContentTypeConstantsInfo class provides two methods that help to determine the type of content returned by the Unified Search Service in a search result. The getAllContentTypes() method returns a bitwise or combination of all the content type constants defined in the SearchableContentTypeConstants class. The getMediaContentTypes() method returns a bitwise or combination of all the media content types in SearchableContentTypeConstants.
Two new constants in SearchableContentTypeConstants can help you to identify media files. The CONTENT_TYPE_MEDIA_DOCUMENTS constant identifies document files. The CONTENT_TYPE_MEDIA_FILES_ALL identifies all media files (documents, music, ring tones, and so on).
You can compare the return values from these methods to the return values from Searchable.getType() to determine whether a search result contains a particular data type.
The SearchableDataObject class provides an implementation of the SearchableEntity interface. You can extend this class to override the methods that are relevant to your data. The SearchableDataObject class provides defaults for methods that you do not override.
The EntityBasedSearchableProvider class provides an implementation of the EntityBasedSearchable interface. You can add, remove, and update your data in the search index without interacting with the AppContentManager class.
The ExtendedSearchProvider class provides an implementation of the ExternalSearchProvider interface. You must override the search() method to connect to a search engine.
A new constructor for the SearchArguments class allows you to specify the search string only. The SearchArguments(String, String) constructor is deprecated.
Identifying media files
Two constants were added to the SearchableContentTypeConstants class to help identify media files. The CONTENT_TYPE_MEDIA_DOCUMENTS constant identifies document files. The CONTENT_TYPE_MEDIA_FILES_ALL identifies all media files (document, music, ring tone, and so on).
Data volume monitoring on CDMA devices
You can now use the RadioInfo.getNumberOfPacketsSent() and RadioInfo.getNumberOfPacketsRecieved() methods to retrieve the number of packets (IP bytes) sent or received on the transceiver for CDMA devices. Previously, you could only retrieve this information on GSM devices. You can use these methods to track how much data a device is sending and receiving over the network. The RadioInfo class is located in the net.rim.device.api.system package.
Using camera input scene modes
You can use new constants and methods in the net.rim.device.api.amms.control.camera.FeatureControl class to set and retrieve the input scene mode (such as portrait, landscape, sport, snow, macro, and so on) and check if a scene mode is supported by the device. You can use thesetSceneMode() method to set the camera's mode to the scene mode specified in the parameter. The parameter must be one of the constants located in the FeatureControl class prefixed by SCENE_MODE_. The getCurrentSceneMode() method retrieves the currently set scene mode represented by one of the constants prefixed by SCENE_MODE_, and isSceneModeSupported() checks if a scene mode is supported.
Focus control modes
You can use constants and methods in the net.rim.device.api.amms.control.camera.EnhancedFocusControl class to set the focus control mode.
The default focus control of the camera on a BlackBerry® device has changed from single-shot to the best available mode (typically continuous). If you rely on a specific focus mode for your application, you must call it explicitly using these new constants. You can use theFOCUS_MODE_CONTINUOUS, FOCUS_MODE_FIXED and FOCUS_MODE_SINGLESHOT to explicitly set the focus mode of the camera to continuous, fixed, and single shot auto-focus respectively. You can pass these constants into the setFocusMode(String mode) method to set the camera's focus mode. You can retrieve the camera's current focus mode using the getCurrentFocusMode() method. You can check if a specific focus mode is supported by passing in one of the above constants into the isFocusModeSupported(String focusModeID) method, which will return true if it is supported, and false otherwise.
Recording video without audio
When creating a video recording player, you can now specify none as a value for the audio_codec parameter. When you specify none, the video records without audio. In addition, System.getProperty("audio.encodings") now returns none as an allowable value for the audio_codec parameter.
Query supported bitrates for various codecs
You can invoke System.getProperty("audio.encodings.bitrate.ranges") and System.getProperty("video.encoding.bitrate.ranges") to retrieve a list of bitrate ranges for the supported codecs.
Setting the audio and video bitrate in video recordings during initialization
You can specify the bitrate for audio and video codecs when you create a Player instance using the Manager class by setting the rate parameter. For example: createPlayer("capture://video?encoding=video/3gpp&rate=<bitrate>&video_rate<bitrate>").
Bitrate ranges for various codecs can be obtained using System.getProperty("audio.encodings.bitrate.ranges") and System.getProperty("video.encoding.bitrate.ranges").
Advanced video control interface
You can use the new AdvancedVideoControl interface, located in the net.rim.device.api.media.control package, to define a new video display mode. This new mode allows you to render core UI components over video fields (for example, playback controls). The interface has one constant, USE_GUI_ADVANCED, that is used as a parameter in the VideoControl.initDisplayMode(int mode, Object arg) method.
Buffer configuration API
You can use the StreamingBufferControl interface, located in the net.rim.device.api.media.control package, to control the internal streaming buffers of the media player. The flush() method clears all data that is currently buffered (but not yet played) by the media player. The setBufferTime(int millis) method controls the amount of time to buffer before playback begins.
VoIP on CDMA-based devices
You can enable VoIP functionality on CDMA-based devices with the voipMode and rate parameters of the javax.microedition.media.Manager.createPlayer(String locator) method.
RTSP fast content switching
When you use the RTSP protocol to display video, you can now switch video feeds without reconnecting to the server (if supported) by using the new RtspContentControl interface located in the net.rim.device.api.media.control package. This process may result in faster and more efficient content switching.
The NFC package enables you to read and write data on smart tags, emulate a smart tag, and access a Secure Element embedded on a BlackBerry® device or SIM card. The NFC API supports most major tag types. You can check the ability of a device to support NFC by using the DeviceCapability classes in the net.rim.device.api.system.capability package.
To read and write to smart tags, you can register your application to receive notifications when a BlackBerry device detects a tag. Depending on the type of tag, and whether you wish to read or write, you must implement different listeners, and register them with the ReaderWriterManager class in the net.rim.device.api.io.readerwriter package.
To use your device to emulate a smart tag, you can use the net.rim.device.api.io.nfc.emulation package. To connect smart accessories to your device, you can use the net.rim.device.blackberry.api.accessory.AccessoryManager class, and you can use the net.rim.device.api.io.nfc.se package to access a Secure Element.
The Locator class in the net.rim.device.api.lbs package has been deprecated, and replaced by new geocoding and reverse geocoding APIs. Using these APIs, you can perform geocoding and reverse geocoding requests asynchronously and synchronously. To initiate an asynchronous request, you must provide a ServerExchangeCallback implementation. Otherwise the request is synchronous. The geocoding and reverse geocoding APIs are provided in the net.rim.device.api.lbs.maps.server and net.rim.device.api.lbs.maps.server.exchange packages.
Dynamic mappable framework
The dynamic mappable framework allows you to create locations on a map, specify if a location needs to be updated, and re-render the map when the location is updated. For example, you can display the location of a BlackBerry Messenger contact in near real-time on a map as the contact's location changes. The dynamic mappable framework is provided in the net.rim.device.api.lbs.maps.model package.
You can define styles for single mappable items or classes of mappable items using the Styles framework. You can also adjust the line edge (weight, opacity, and color), the fill (opacity and color), and the label (fill and font) for mappable items. The Styles framework is located in the net.rim.device.api.lbs.maps.view package.
Building block framework
You can create mappable objects that correspond to geospatial shapes such as polygons, polylines, images, lines, markers, and points using the Building block framework. Shapes (for example, images or polygons) are provided in the net.rim.device.api.lbs.maps.model package. Geospatial shapes which correspond to these shapes are provided in the net.rim.device.api.lbs.maps.model.geospatial package. You can use these shapes to do various things. such as display BlackBerry® Messenger profile pictures as markers for locations on a map.
You can add a compass overlay to your application by using the CompassField class, which is provided in the net.rim.device.api.lbs.compass package. The CompassField provides a graphical representation of a compass to provide directional context (for example, in a mapping application, the compass displays where north is in relation to the BlackBerry® device user's current location). You can create an instance of CompassField and add it to a field manager, like other UI components in the BlackBerry® Java® SDK.
MapField and MapAction enhancements
The MapAction and MapField classes, which are provided in the net.rim.device.api.lbs.maps.ui package, provide new methods that allow you to perform specific actions on a map field. The classes support actions such as setting the center, zoom, and rotation level of a map field.
Retrieving the bearing between two locations
You can retrieve the compass initial bearing between two specified locations by using getBearing() method that is defined in the net.rim.device.api.gps.LocationInfo class. You must provide the geographic coordinates (latitude and longitude) for the starting and ending locations, and then invoke getBearing(), which calculates the angle (in degrees) between the two locations.
You can use the Geofence class to define geofenced areas and receive notifications when a BlackBerry® device user enters or leaves the specified area. A geofence is a virtual geographic area of interest that you can define by a radius around a location, or by coordinates that define a polygon for the location.
Your application must create an instance of a Geofence object, and implement GeofenceListener to receive notifications for geofencing events (when a user enters or exits geofenced areas). Each instance of Geofence is designed to process up to 20 monitored areas concurrently. Geofence is provided in the net.rim.device.api.location package.
Retrieving a bounding box
You can retrieve the mappable (that is, latitude and longitude-based) bounding box for a mappable item by using getBoundingBox(). The classes which implement the Mappable interface define this method. A mappable bounding box represents a rectangular area that a mappable item occupies on a map.
Departure time estimation
The Travel Time API is enhanced. You can now specify an arrival time, and request an estimated departure time. The Travel Time API is provided in the net.rim.device.api.lbs.travel package, and can now request estimated departure and arrival times given your current location.
OpenGL ES 2.0
OpenGL® ES 2.0 is supported with the addition of the GL20 interface that is defined in the net.rim.device.api.opengles package. OpenGL ES 2.0 is also supported in the GLField class. Improvements in the GLUtils class, and a new set of utility methods are designed to help you use OpenGL ES 1.1 and 2.0. The GLUtils class is implemented in the net.rim.device.api.opengles package.
You can now load an EncodedImage as a texture for a 3D object, a portion of a EncodedImage or Bitmap into a texture. You can also load shader programs.
The VGUtils class provides a set of utility methods that are designed to make it easy for you to use OpenVG™. The VGUtils class is implemented in the net.rim.device.api.openvg package.
You can create a VGImage from a region of a Bitmap or EncodedImage. You can create a VGPath from SVG path data, and use a simpler method to create linear or radial gradient paths. You can also append path segments to a VGPath, create text in a VGPath or a VGImage by specifying the text to create and the font to use. You can draw text as image glyphs or path glyphs, and control if text glyph outlines are filled, stroked, or both, and measure text without drawing it. You can load image data from a region of a Bitmap or EncodedImage into a region of a VGImage.
Matrix3f and Matrix4f classes in the net.rim.device.api.math package were enhanced with methods to help you work with and create various types of matrices used by OpenGL® ES and OpenVG™. The Matrix3f.shear() method transforms a matrix to incorporate a specified amount of shear along two axes.
The createBillboard(), createLookAt(), createOrthographic(), createPerspective(), and createReflection() methods on Matrix4f, are designed to make it easy to construct matrices you might require when using OpenGL ES.
RIM Cryptographic API
The AES implementation in the RIM Cryptographic API has changed. Prior to BlackBerry Java SDK 7.0, a FIPS-validated version of the AES encryption algorithm was always used, but with BlackBerry 7, the BlackBerry device chooses the version of AES that allows for the best performance. This flexibility is possible because BlackBerry devices that run BlackBerry 7 do not use FIPS compliant AES implementations by default. Most developers do not need to create FIPS compliant applications. The option to enforce FIPS compliance on BlackBerry devices is available in a BlackBerry Enterprise Server environment. To enforce FIPS compliance, your BlackBerry Enterprise Server administrator must set the new IT policy rule "Enforce FIPS Mode of Operation."
A new FIPS-validated random source was added: the AES cipher-based deterministic random bit generator. It is represented by a new constant in the Crypto class, PRNG_TYPE_AES_CTR_DRBG. In addition, a constant was added: PRNG_TYPE_FIPS186. Previously, this was the only random number generator; as the only type, it did not need to be specified. This random number generator is no longer FIPS compliant. A new variable, prngType, is now supported by the Crypto.getPRNG() method. It can be set to PRNG_TYPE_AES_CTR_DRBG (for FIPS compliance) or PRNG_TYPE_FIPS186 (for no FIPS compliance)
The AESEncryptorEngine(), AESDecryptorEngine(), AESCBCEncryptorEngine(), and AESCBCDecryptorEngine() methods each have a new Boolean parameter called useFIPSmode. A parameter name was changed in AESEncryptorEngine(), AESDecryptorEngine(), AESCBCEncryptorEngine(), and AESCBCDecryptorEngine(). The parameter inECMMode is changed to useCPAProtection. This name change does not affect functionality.
The AESCTRDRBGPseudoRandomSource class was added. TheAESCTRDRBGPseudoRandomSource class is identical to FIPS186PseudoRandomSource, except that the new class supports FIPS compliance. The FIPS186PseudoRandomSource class can no longer be used to generate pseudorandom data in FIPS compliant applications, but it can still be used for applications that do not require FIPS compliance.
BlackBerry Balance technology support
The Multi Service Platform API supports the BlackBerry Balance technology that was introduced in BlackBerry Enterprise Server 5.0.3.
BlackBerry Enterprise Server administrators can set IT policy rules that controls access to work data and personal data on a BlackBerry device. These rules allow administrators to control access to work data, as well as facilitating the deletion of work data.
The net.rim.device.api.system.MultiServicePlatformManager class and the net.rim.device.api.system.MultiServicePlatformListener interface allow you to implement controls on data access and create listeners that allow administrators to delete data remotely. Modes (such as work) are defined in the net.rim.device.api.system.ServiceMode class. The net.rim.device.api.system.Application class includes the following new methods: getServiceMode, setServiceMode, setServiceModeImpl, and suggestServiceMode.
The PL_INVALID_OPERATION constant has been added to the FileIOException class. The PL_INVALID_OPERATION exception is generated when an unauthorized, personal or non-work application attempts to delete, create, read, or change a work file.
Security for NFC
The PERMISSION_NFC and PERMISSION_SECURE_ELEMENT constants have been added to the ApplicationPermissions class. PERMISSION_NFC controls an application's ability to access NFC functionality. PERMISSION_SECURE_ELEMENT controls an application's ability to access the secure elements embedded in the phone or on a SIM card.
You can specify both permissions to VALUE_ALLOW, VALUE_PROMPT, or VALUE_DENY. The default value for both permissions is VALUE_PROMPT. You can find the ApplicationPermissions class in the net.rim.device.api.applicationcontrol package.
The BlackBerry Java SDK 7.0 uses SQLite version 3.7.2. BlackBerry Java SDK 6.0 used SQLite 3.6.21. For a description of the new features in SQLite, see the SQLite documentation, available at www.sqlite.org.
The amount of RAM available to an SQLite database for storing internal data structures for schemas and transactions has increased to 16 MB (from 5 MB in 6.0). A query can now be up to 1 MB. In BlackBerry Java SDK 6.0, the query length limit was 4 KB. The file handle limit has increased to 64, allowing you to open up to 56 databases at the same time in In BlackBerry Java SDK 7.0.
In addition, you can now choose to use a write-ahead log instead of the rollback journal. The write-ahead log provides increased concurrency because writing to the database does not block reading. You can use a write-ahead log by setting the WAL option in the journal_mode pragma. You can also use shared-cache mode to help lower memory usage for multiple connections to the same database.
SQLite as a service
When you create a prepared statement for inserting or updating data, you can use Statement.executeInsert() and Statement.executeUpdate(), to reduce the number of calls over the runtime bridge. These methods perform the following operations in native code: bind SQL parameters, execute the statement, reset the statement, and clear bindings. In addition, executeInsert() returns the last inserted row ID.
When you execute a query that doesn't return a result set and you are not binding parameters, you can use Database.executeStatement() to reduce calls over the runtime bridge. This method performs the following operations in native code: prepares the statement, executes the statement, and finalizes the statement.
When using Statement.getCursor() to execute a query that returns result sets, you can now pre-fetch a specified number of rows by using Statement.setCursorBufferSize(). Using this method reduces the use of the runtime bridge. When the cursor moves past the buffered set, a new batch of rows is fetched. You can retrieve the number of rows a cursor buffers with the new method Statement.getCursorBufferSize().
When you retrieve integer values to use as keys in another query, you can use Statement.getIntegers() and Statement.getLongs(). These methods help to simplify and optimize the retrieval of integer columns.
Enhanced functionality for handling blobs
New methods for handling blobs eliminate the need to store the entire blob in application memory, so the amount of available dynamic memory does not limit the blob size that can be read to or written from the database. Database.createBlobOutputStream() creates an OutputStream object that is used to write data into a blob, and Database.createBlobInputStream() creates an InputStream object that is used to read data from a blob.
The Statement.bindZeroBlob() method allows you to bind a series of null bytes to a parameter in a Statement. You can use the bindZeroBlob method to reserve space for blob output when you use Database.createBlobOutputStream() to write data into a blob and execute the Statement with Statement.execute().
You can now use a subset of SQLite PRAGMA statements. The net.rim.device.api.database.Pragma class contains constants for each supported pragma. The following pragmas are supported:
Attaching and detaching databases
To attach or detach databases from an existing database connection, two new methods have been added, Database.attach() and Database.detach(). These methods are designed to allow you to attach up to ten databases to a connection. You can use the DETACH command in an SQL statement, but you cannot use the ATTACH command in an SQL statement.
Behavior changes for buffered cursors
The BufferedCursor.isEmpty() method no longer moves through the cursor under any circumstances, and no longer returns false when the cursor position is one more than the last row available.
The BufferedCursor.prev() method repositions the cursor to the initial position (-1) when it is called multiple times.
Language collation is now supported. For example, you can now create a table that has French language collation enabled on a column. The following collation sequences are supported:
- Hong Kong Chinese
- Taiwanese Chinese