Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Java Development

Simple Location API

by BlackBerry Development Advisor on ‎06-13-2011 01:37 PM - edited on ‎12-20-2011 04:21 PM by BlackBerry Development Advisor (13,261 Views)



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

 sla.jpg

 

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