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

Leverage the Location API

by Retired ‎02-12-2010 02:12 PM - edited ‎09-17-2010 04:31 PM (5,347 Views)

1 Introduction

This lab demonstrates the basics of how to leverage the Location API (JSR179) of the BlackBerry platform. Upon completion of this lab, one should be able to write a location based application for the BlackBerry platform. The application we are going to write is called “WhereAmI” which simply shows your current location coordinates on the Screen. It has three menu items: “Get Single Fix” which simply gets the current location information and displays it and “Start Multiple Fix” which keeps getting location data at fixed intervals and displays it on the Screen until “Stop Multiple Fix” is selected.

 

 

2 Tasks

  1. Setup and create a Criteria object
  2. Create a LocationProvider
  3. Implement LocationProvider reset logic
  4. Get a single location fix data using the LocationProvider
  5. Implement a LocationListener
  6. Get multiple location data at fixed intervals using a LocationListener

 

 

2.1 Task 1: Setup and create a Criteria object.

A Criteria object dictates in what GPS mode a LocationProvider is going to operate. There are several GPS modes available on CDMA and GSM networks. However, that discussion is beyond the scope of this lab. Please refer to BlackBerry Developer Knowledge Base Articles for more information.

 

In this task, we will setup a Criteria object so that the LocationProvider is not allowed to cost the user anything, i.e. it cannot operate in any mode that might trigger carrier charges.

 

2.1.1 Create a Criteria instance

First, we need to instantiate our Criteria object. We will write a method called setupCriteria() which takes care of this. In the code, go to the TODO step titled “Create a Criteria instance” in the method setupCriteria() and call the Criteria constructor to instantiate the Criteria object named _criteria.

 

 

Solution

_criteria = new Criteria();

 

2.1.2 Set CostAllowed to false

Go to the TODO step titled “Set CostAllowed to false” in the method setupCriteria() and set the cost allowed property of the Criteria to false.

 

Solution

_criteria.setCostAllowed(false);

 

2.2 Task 2: Create a LocationProvider

Once we have our Criteria object ready, we can instantiate our LocationProvider _provider.

 

2.2.1 Get a LocationProvider instance and set it to _provider

To instantiate our LocationProvider, we are going to write a method called createLocationProvider(). In the code, go to the TODO step titled “Get a LocationProvider instance and set it to _provider” in the method createLocationProvider() and use the static factory method of LocationProvider class to get an instance of LocationProvider using the Criteria object named _criteria.

 

Solution

_provider = LocationProvider.getInstance(_criteria);

 

2.3 Task 3: Implement LocationProvider reset logic

It is a good practice to reset the LocationProvider when we want to stop getting fixes at fixed intervals or when we simply want to start fresh. This task will demonstrate the recommended way to reset a LocationProvider. For more details on other cases when a reset is recommended, please refer to the BlackBerry Developer Knowledge Base Articles.

 

2.3.1 Implement LocationProvider reset logic

In the code go to the TODO step titled “Implement LocationProvider reset logic” in the method resetProvider(). Write code to remove any LocationListener that is registered with the LocationProvider in question, to reset the LocationProvider and to set the LocationProvider to null.

 

Solution

if(_provider!=null){

      _provider.setLocationListener(null, 0, 0, 0);

_provider.reset();

      _provider=null;

}

 

2.4 Task 4: Get a single location fix data using the LocationProvider

This is the most straightforward way to get location fix data. Once the Criteria and LocationProvider are ready, we can simply call the public method LocationProvider.getLocation(int timeout) to get a Location object which contains the longitude, latitude and altitude of the location fix.

 

2.4.1 Reset the LocationProvider

We want to start fresh here. So lets remove any LocationListener that might be registered before and reset the provider. In the code, go to the TODO step titled “Reset the LocationProvider” in the method getSingleFix() and call the resetProvider() method that we have implemented.

 

Solution

resetProvider();

 

2.4.2 Call setupCriteria() and createLocationProvider()

Now we need to call our setupCriteria() and createLocationProvider() method to create our Criteria and LocationProvider objects. Go to the TODO step titled “Call setupCriteria() and createLocationProvider()”in the method getSingleFix() and do so.

 

Solution

setupCriteria();

createLocationProvider();

 

2.4.3 Get single location fix

At this point we have everything setup to get a single location fix data that will have the coordinates. In the code, go to the TODO step titled “Get single location fix” in the method getSingleFix() and call the getLocation() method of our LocationProvider object and store it in the Location variable named _location. Please note that we must create a separate Thread to call this method but that is already taken care of in the code.

 

Solution

_location = _provider.getLocation(-1);

 

2.4.4 Validate Location object

If the LocationProvider was unable to return a proper Location object according to the Criteria we have setup, it will return an invalid Location object. So we must check if our Location object is valid before we go on to get the coordinates from the Location object. In the code go to the TODO step titled “Validate Location object” in the method getSingleFix().

 

Solution

if(_location!=null && _location.<call validation method>{  

...

}

 

2.4.5 Get QualifiedCoordinates from _location

Once our Location object is validated, we can read the coordinates from our Location object named _location. Go to the TODO step titled “Get QualifiedCoordinates from _location” in the method getSingleFix() and call getQualifiedCoordinates() method of _location.

 

Solution

QualifiedCoordinates coordinates = _location.getQualifiedCoordinates();

 

2.4.6 Display coordinates

Now we can display the coordinates for longitude, latitude and altitude on the Screen. We are going to use the log(String msg) method implemented in the code which simply displays msg in an EditField on the Screen. To do that, go to the TODO step titled “Display coordinates” in the method getSingleFix().

 

Solution

log("Longitude: "+coordinates.getLongitude());

log("Latitude: "+coordinates.getLatitude());

log("Altitude: "+coordinates.getAltitude());

 

2.5 Implement a LocationListener

We need to implement a LocationListener to facilitate location fixes at fixed intervals. As you might have noticed, our WhereAmI class implements LocationListener which means that we must provide implementation for the following methods:

public void locationUpdated(LocationProvide, Location)

public void providerStateChanged(LocationProvider, int) 

 

locationUpdated() is invoked at fixed interval with the updated location information as an argument and providerStateChanged() is called whenever the state of the LocationProvider changes. providerStateChanged() is beyond the scope of this lab. Please refer to BlackBerry Developer Knowledge Base Articles for more information.

 

2.5.1 Validate Location object

Whenever the locationUpdated() method is invoked by our LocationProvider, we must first validate the Location object as before. Go to the TODO step titled “Validate Location object” in the method locationUpdated(). Please note that in this case we are validating the Location object named location which is passed as an argument to the locationUpdated() method.

 

Solution

if(location!=null && location.isValid()){

...

}

 

2.5.2 Get QualifiedCoordinates from location

Once our Location object is validated, we can read the coordinates from our Location object named location which is an argument of the getLocation() method. Go to the TODO step titled “Get QualifiedCoordinates from location” in the method locationUpdated() and call getQualifiedCoordinates() method of location.

 

Solution

QualifiedCoordinates coordinates = _location.getQualifiedCoordinates();

 

2.5.3 Display coordinates

Now we can display the coordinates for longitude, latitude and altitude on the Screen. We are going to use the log(String msg) method implemented in the code which simply displays msg in an EditField on the Screen. To do that, go to the TODO step titled “Display coordinates” in the method locationUpdated().

 

Solution

log("Longitude: "+coordinates.getLongitude());

log("Latitude: "+coordinates.getLatitude());

log(Altitude: "+coordinates.getAltitude());

 

2.6 Task 5: Get multiple location data at fixed intervals using a LocationListener

For application that requires frequent GPS fixes (e.g. every 5 seconds) it is recommended to implement (as we did) and register a LocationListener which gets location updates at fixed intervals.

 

2.6.1 Reset the LocationProvider

We want to start fresh here again. So lets remove any LocationListener that might be registered before and reset the provider. In the code, go to the TODO step titled “Reset the LocationProvider” in the method getMultipleFix() and call the resetProvider() method that we have implemented.

 

Solution

resetProvider();

 

2.6.2 Call setupCriteria() and createLocationProvider()

Now we need to call our setupCriteria() and createLocationProvider() method to create our Criteria and LocationProvider objects. Go to the TODO step titled “Call setupCriteria() and createLocationProvider()” in the method getMultipleFix() and do so.

 

Solution

setupCriteria();

createLocationProvider();

 

2.6.3 Register LocationListener

Last but not least, we need to register our LocationListener with a LocationProvider. In the code go got the TODO step titled “Register LocationListener” in the method getMultipleFix() and register our LcoationListener with our LocationProvider _provider by calling setLocationListener() method of _provider which takes 4 arguments – LocationListener, interval, timeout and maxAge. Use “this” as the LocationListener, 5 as the interval and -1 for both timeout and maxAge. This means that we are using 5 seconds as the interval and default values for timeout and maxAge. Registering a LocationListener will immediately start the LocationProvider which will call locationUpdated() method of the registered listener repeatedly at the fixed interval we defined.

 

Solution

_provider.setLocationListener(this, 5, -1, -1);

 

 

3 Conclusion

This brings us to the end of this lab. Please feel free to browse our Developer Knowedge Base Articles and Developer Video Library for more advanced topics on the Location API.

 

 

-----THE END----

Contributors
Users Online
Currently online: 36 members 2,195 guests
Please welcome our newest community members: