Location-based services

Dynamic mapping enhancements

The Dynamic Mappable framework allows you to create locations on a map, specify if a location needs to be updated, and re-renders the map when the location is updated. For example, you can display the location of a BlackBerry® Messenger contact in real-time on a map as their location changes.

The Dynamic Mappable framework is provided in the net.rim.device.api.lbs.maps.model package and it includes the following key classes:

  • DynamicMappable: Defines a mappable object with changeable contents, and registers for notifications of any change events
  • MappableEventManager: Manages the events and listeners for dynamic and mappable objects
  • MappableEventListener: Listens for any changes to a dynamic mappable object
  • MappableChangeEvent: Captures the contents of an event that has occurred to a dynamic mappable object

Custom shape creation

The Building Block framework allows you to create mappable objects that correspond to complex geospatial shapes such as polygons, polylines, images, lines, markers, and points. For example, you can display BlackBerry Messenger profile pictures as markers for locations on a map.

Basic shapes (such as images or polygons) are provided in the net.rim.device.api.lbs.maps.model package. Corresponding geospatial shapes are provided in the net.rim.device.api.lbs.maps.model.geospatial package. The geospatial shapes (prefixed with Gs<shape>) are more robust than the basic shapes (prefixed with Map<shape>) because the geospatial shapes can be organized in a tree structure using GsFolder and GsRoot, which is similar to KML-structured elements. You can also assign names and descriptions to the geospatial shapes.

The following classes can be found in the net.rim.device.api.lbs.maps.model package:

  • MapImage: Represents an image for a location on a map. You can specify an image, a thumbnail, or a URI for the location. When you specify a thumbnail, the thumbnail displays directly on the map. When the user clicks on the thumbnail and requests more details, the larger image displays.
  • MapLine: Represents a line segment on the map.
  • MapMarker: Represents a marker point on the map. You can specify a URI for the marker point.
  • MapPolyLine: Represents a continuous line that is composed of line segments between an ordered set of MapPoint objects.
  • MapSimplePolygon: Represents a simple polygon. The simple polygon renders faster than the complex polygon.
  • MapComplexPolygon : Represents a polygon that is composed of an outer boundary (defined as an ordered series of MapPoints), and inner boundary (0 or more MapSimplePolygons).
  • PeerPoint: Represents a static location, with accuracy. For example, you can use a PeerPoint to indicate the BlackBerry device user's last location.

The following classes can be found in the net.rim.device.api.lbs.maps.model.geospatial package:

  • GsElement: Defines the interface that is implemented by all geospatial features.
  • GsFolder: Represents a folder that you can use to store GsElement objects.
  • GsRoot: Represents the top-level container for a hierarchy of GsElement objects and StyleSet objects that are used to render the content.

Define styles for mappable items

The Styles framework allows you to define styles for single mappable items or classes of mappable items. You can adjust the line edge (weight, opacity, and color), the fill (opacity and color), and the label (fill and font) for mappable items.

The Styles APIs are provided in the net.rim.device.api.lbs.maps.view package and it includes the following key elements:

  • Style: Provides a set of properties that you can use to define how a mappable item should be drawn.
  • StyleSet: Represents a set of styles that you can apply to a class or to objects that have a specific ID. For example, objects that have the "Friend" ID have the "Friend" styles applied.

MapField and MapAction enhancements

The MapAction and MapField classes, which are included 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 MapAction class includes actions such as setting the center, zoom, and rotation level of a map field. These actions are represented by methods that have a set<Action> prefix (such as setRotation). The set method determines if the action is allowed, and if it's allowed, the action is performed. Each set method has an associated allow<Action> (such as allowSetRotation) and perform<Action> (such as performSetRotation) method, which you can override to create a custom action. For example, if you don't want the user to change the zoom level, subclass the MapAction class, and override the allowSetZoom() method to return false.

Departure time estimation

The Travel Time API has been enhanced so that you can request an estimated departure time for a specified expected arrival time. The Travel Time API is provided in the net.rim.device.api.lbs.travel package and it includes the following updates:

  • TravelTimeEstimator.requestDepartureEstimate(): Requests an estimated departure time. You can use this method with a listener to retrieve an estimate asynchronously, or without a listener to retrieve the estimate synchronously.
  • TravelTime.getEndTime(): Retrieves the arrival time at the destination.
  • TravelTime.setEndTime(): Sets the arrival time at the destination.

Monitor a geofenced area

You can use the Geofence class that's provided in the net.rim.device.api.location package 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 instantiate a Geofence object and implement the GeofenceListener to receive notifications for geofencing events (when a user enters or exits geofenced areas). Each instance of Geofence can process up to 20 monitored areas concurrently.

Retrieve the bearing between two locations

You can retrieve the compass initial bearing between two specified locations by using the getBearing() method that is defined in the net.rim.device.api.gps.LocationInfo class. You must provide the geographic coordinates (latitude/longitude) for the starting and ending locations, and then invoke getBearing(), which calculates the angle (in degrees) between the two locations.

Retrieve a bounding box

You can retrieve the latitude and longitude-based bounding box for a mappable item by using the getBoundingBox() method. All classes implementing the Mappable interface define this method. A mappable bounding box represents a rectangular area that a mappable item occupies on a map.

Add a compass overlay to your application

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 that can be added to your application to provide directional context (for example, in a mapping application, the compass displays where North is in relation to the user's current location). You can instantiate CompassField and add it to a field manager like other UI components that are used in the BlackBerry® Java® SDK.

Support for performing asynchronous and synchronous geocoding and reverse geocoding requests

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.

Note: The Locator class that is provided in the net.rim.device.api.lbs class has been deprecated and replaced by these new geocoding and reverse geocoding APIs.

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 and include the following key classes:

  • Geocoder: Provides methods to request the latitudinal and longitudinal coordinates for a given address. The address can be a free-form search string or a structured search string (e.g. an AddressInfo object).
  • GeocodeExchange: Handles the geocoding request and response. The request is made through the Geocoder class, but the response and results are returned as an instance of GeocodeExchange.
  • ReverseGeocoder: Provides methods to request an address for a given set of coordinates.
  • ReverseGeocodeExchange: Handles the reverse geocoding request and response. The request is made through the ReverseGeocoder class, but the response and results are returned as an instance of ReverseGeocodeExchange.
  • ServerExchangeCallback: Represents the interface that is called when the geocoding or reverse geocoding request completes.
Previous topic: Multimedia

Was this information helpful? Send us your comments.