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

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