Welcome to the Official BlackBerry Support Community Forums. This is your resource to discuss support topics with your peers, and learn from each other. New to the forum? Please visit the ‘Getting Started’ link below.

Getting Started

All New Topics | All New Posts

Java Development

Simple Location API

Started 06-13-2011 by

Modified 12-20-2011 by

Simple Location API, as the name suggests, is a simplified version of the Location API packages available on the BlackBerry® development platform. This API is built on top of the existing Location APIs and offers a simple, worry-free but feature-rich API that will hopefully allow the developers to focus on their application instead of spending a lot of time on the complex details and corner cases of standard Location APIs. The source code of this API is now Open Source and can be downloaded along with a demo application from Github: https://github.com/blackberry/Samples-for-Java/tree/master/Simple%20Location%20API

NOTE: The API supports BlackBerry® Device Software 5.0 and onwards and has preprocessor statements to leverage BlackBerry Device Sofware 5.0 and BlackBerry® 6.0 features. To use this API in 5.0, the code snippets enclosed in //#ifdef BlackBerrySDK6.0.0 and following //#endif must be removed. Similarly, when targeting BlackBerry 6.0 and later, the code snippets enclosed in //#ifdef BlackBerrySDK5.0.0 and following //#endif must be removed. If you are using BlackBerry® Java® Plug-in for Eclipse®, the preprocessors should be automatically taken care of by the IDE based on your selected BlackBerry® Java Runtime Environment for the project.

Simple Location API features:

Simplified with a focus on real world usecases. Consists of only two classes.
Worry-free location API that leverages on-device GPS and RIM's Geolocation services.
Dynamically detects available and supported location modes on the device before trying any of them.
Chooses the best location mode based on the modes available on the device.
Built-in retry mechanism with dynamic delay (to save battery) based on a retry factor set by the API user.
Performs both single or tracking location fixes.
Simplified events via SimpleLocationListener interface.
Capable of starting, stopping and restarting tracking session in a reliable thread-safe way.
Designed to eliminate/reduce misuse of location API

Examples

Single location fix in default mode

 try{
        simpleProvider = new SimpleLocationProvider();
 } catch(LocationException le){ // thrown if the default mode MODE_OPTIMAL is not available.
        ...
 }
 BlackBerryLocation location = simpleProvider.getLocation(120); // 120 seconds timeout

Single location fix in a specified mode:

 try{
        simpleProvider = new SimpleLocationProvider(SimpleLocationProvider.MODE_GPS);
 } catch(LocationException le){ // thrown if the selected mode (in this case MODE_GPS) is not available.
        ...
 }
 BlackBerryLocation location = simpleProvider.getLocation(120); // 120 seconds timeout

Tracking session in default mode

 try{
        simpleProvider = new SimpleLocationProvider();   
 } catch(LocationException le){ // thrown if the default mode MODE_OPTIMAL is not available.
        ...
 } 
 // Location fixes will be delivered to simpleLocationListenerImpl (an implementation of SimpleLocationListener) every 6 seconds.
 simpleProvider.addSimpleLocationListener(simpleLocationListenerImpl, 6);

Tracking session in a specific mode

 try{
        simpleProvider = new SimpleLocationProvider(SimpleLocationProvider.MODE_GPS);    
 } catch(LocationException le){ // thrown if the selected mode (in this case MODE_GPS) is not available.
        ...
 } 
 // Location fixes will be delivered to simpleLocationListenerImpl (an implementation of SimpleLocationListener) every 6 seconds.
 simpleProvider.addSimpleLocationListener(simpleLocationListenerImpl, 6);

rimx.location.simplelocation

Class SimpleLocationProvider

This is the starting point for applications using the Simple Location API. An instance of this class must be

created in order to get a single location fix or to start a tracking session

Author:: Shadid Haque

Field Summary
`static int`	`MODE_GEOLOCATION` Operates strictly in Geolocation mode.
`static int`	`MODE_GEOLOCATION_CELL` Operates strictly in cell based Geolocation mode.
`static int`	`MODE_GEOLOCATION_WLAN` Operates strictly in WLAN based Geolocation mode.
`static int`	`MODE_GPS` Operates strictly in GPS (aka Standalone/Autonomous) mode.
`static int`	`MODE_OPTIMAL` Operates in both Geolocation and GPS mode based on availability.

Constructor Summary
`SimpleLocationProvider()` Initializes the default SimpleLocationProvider in MODE_OPTIMAL.
`SimpleLocationProvider(int mode)` Initializes a SimpleLocationProvider in the specified mode.

Method Summary
`void`	`addSimpleLocationListener(SimpleLocationListener listener, int interval)` Adds a SimpleLocationListener implementation to this SimpleLocationProvider and starts a tracking session.
`int`	`getGeolocationTimeout()` Gets the current value of Geolocation timeout.
`int`	`getGPSTimeout()` Gets the current value of GPS timeout.
`BlackBerryLocation`	`getLastKnownLocation()` Returns the last known location.
`BlackBerryLocation`	`getLocation(int timeout)` Gets a single location fix and stops.
`int`	`getMaxRetryDelay()` Gets the current value of maxRetryDelay.
`int`	`getMode()` Returns the current mode of this SimpleLocationProvider
`int`	`getRetryFactor()` Gets the current retry factor.
`int`	`getTrackingInterval()` Gets the current tracking interval.
`void`	`locationUpdated(LocationProvider provider, Location location)` This is used by this API internally and must NOT be called.
`void`	`log(String msg)` Logs a message to standard output as well as to the device eventlog.
`void`	`providerStateChanged(LocationProvider provider, int newState)` This is used by this API internally and must NOT be called.
`void`	`removeSimpleLocationListener()` Removes the current SimpleLocationListener implementation from this and stops tracking session.
`void`	`restart()` Triggers an immediate retry to get location fixes again.
`void`	`setGeolocationTimeout(int timeout)` Sets the Geolocation timeout.
`void`	`setGPSTimeout(int timeout)` Sets the GPS timeout.
`void`	`setMaxRetryDelay(int delay)` Sets the maxRetryDelay value that dictates the maximum time this provider can wait until a retry is performed.
`void`	`setMode(int mode)` Sets/changes the current mode of this SimpleLocationProvider.
`void`	`setRetryFactor(int factor)` Sets the retry factor to the specified value.
`void`	`setTrackignInterval(int interval)` Sets the interval used between fixes in a tracking session.

rimx.location.simplelocation

Interface SimpleLocationListener

Implement this interface to listen for events triggered by SimpleLocationProvider for a tracking session. Implementation of this interface should be registered with SimpleLocationProvider by calling SimpleLocationProvider.addSimpleLocationListener(SimpleLocationListener, int). Otherwise, no tracking session will be started and no location fixes will be delivered to this listener interface. Only one SimpleLocationListener implementation can be registered with a SimpleLocationProvider.

 // The following call registers simpleLocationListenerImpl (a SimpleLocationListener implementation) to receive location updates every 5 seconds.
 simpleLocationProvider.addSimpleLocationListener(simpleLocationListenerImpl, 5);
 
 // The following call removes simpleLocationListenerImpl (a SimpleLocationListener implementation) and stops any further location updates.
 simpleLocationProvider.removeSimpleLocationListener();


Author:: Shadid Haque

Field Summary
`static int`	`EVENT_ACQUIRING_LOCATION` Triggered when the SimpleLocationProvider starts/restarts to acquire a location fix.
`static int`	`EVENT_CELL_GEOLOCATION` Triggered when a location is obtained via cell tower based geolocation.
`static int`	`EVENT_GPS_LOCATION` Triggered when a location is obtained via GPS.
`static int`	`EVENT_LOCATION_FAILED` Triggered when obtaining a location fix fails within the specified timeout - (See `SimpleLocationProvider.setGeolocationTimeout(int)` and `SimpleLocationProvider.setGPSTimeout(int)`).
`static int`	`EVENT_UNKNOWN_MODE` Triggered when a valid location is obtained but the mode is unknown.
`static int`	`EVENT_WLAN_GEOLOCATION` Triggered when a location is obtained via wlan based geolocation.

Method Summary
`void`	`debugLog(String msg)` Called when a debug message is available.
`void`	`locationEvent(int event, Object eventData)` Triggers one of the EVENT_* events defined in this interface.

Contributors

By downloading, accessing or otherwise using the Knowledge Base documents you agree: (a) that the terms of use for the documents found at http://www.blackberry.com/support/knowledgebase/disclaimer.shtml apply to your use or reference to these documents; and (b) not to copy, distribute, disclose or reproduce, in full or in part any of the documents without the express written consent of RIM.

Top Taggers