Back | Tutorial Home | Next

JSR 179 defines the specification for Location API in J2ME. This API is an optional package and may not be there for all the devices. Check your target device's documentation for JSR 179 support. In some cases especially older models, device vendors may have some their custom Location API's.

Location API is supported by CLDC1.1 and CDC. However CLDC1.0 does not support this API. With Location API you can find your device's position, orientation and also create landmarks.

Package javax.microedition.location

Package javax.microedition.location provides all the necessary Classes, Interfaces and Exceptions for creating Location aware application. The basic classes you will need for a simple location aware application are

LocationProvider

This class is the starting point for all LBS applications and provides us Location Manager. Though we can set rules for LocationProvider through Criteria object, It is operating systems call to return a compatible handle to LocationProvider.

Criteria

Criteria is used to create rules for LocationProvider like accuracy, billing, speed, course, power consumption, response time etc.

 			Criteria cr = new Criteria();
 			// Required Accuracy is set to 100 Meters 
			cr.setHorizontalAccuracy(100);
			LocationProvider provider = LocationProvider.getInstance(cr);

if(provider.getState() == LocationProvider.AVAILABLE) {

}
else if(provider.getState() == LocationProvider.TEMPORARILY_UNAVAILABLE)  { 

}

If the Location Provider is not available the system will throw LocationException. Now that we have a handle to LocationProvider, we can now get all our location information using Location, Coordinates and QualifiedCoordinates

Location

Location encapsulates the header information or Meta information of the present location like speed, course, timestamp, location method etc.

Location.getLocationMethod returns the location tracking method used by the LBS system.

		// 90 secs is the time out
		Location location = provider.getLocation(90);
		int locationMethod = location.getLocationMethod(); 

This is the class which provides our "Where am I?" parameters - latitude, longitude and altitude. We can also create a Location object and compare with the "Where Am I" Coordinates. Here we create the Coordinate object of the Greenwich.

Cunstructor Usage: Coordinates(double latitude, double longitude, float altitude)

Coordinates greenwich = new Coordinates(0, 51, 0);

QualifiedCoordinates

This is a subclass of Coordinates and provides us Coordinates with vertical and horizontal accuracy. Use this object to get all your information.

QualifiedCoordinates c = location.getQualifiedCoordinates();
double latitude = c.getLatitude();
double longitude = c.getLongitude();
float altitude = c.getAltitude();
float hAccuracy = c.getHorizontalAccuracy();
float vAccuracy = c.getVerticalAccuracy();

The above five classes will help us create a basic Location aware application. We will study the more advanced classes like LocationListener, AddressInfo, Orientation, ProximityListener, Landmark, LandmarkStore in the later sections of this tutorial.

The simple LBS System can be summarized in 4 steps

1. Create constraints for LocationProvider using Criteria Class
2. Obtain LocationProvider handle using Criteria object.
3. Get Location Information from LocationProvider Handle.
4. Get Coordinates using Location Object.

Always use threads for your Location Tracking Code.

All your LBS code should be done in a separate thread. As LBS code could sometimes block the system because Location API is resource intensive. The user should be allowed to exit the programs if LBS tracking take more time and resources.

Code Segment of LBS Thread

		// LBS code starts here
    	try {
    		
 			Criteria cr = new Criteria();
 			// Required Accuracy is set to 100 Meters 
			cr.setHorizontalAccuracy(100);
			LocationProvider provider = LocationProvider.getInstance(cr);
			
			if(provider.getState() == LocationProvider.AVAILABLE) {
				// 90 secs is the time out
				Location location = provider.getLocation(90);
				QualifiedCoordinates c = location.getQualifiedCoordinates();
				int locationMethod = location.getLocationMethod(); 
				double latitude = c.getLatitude();
				double longitude = c.getLongitude();
				float altitude = c.getAltitude();
				float hAccuracy = c.getHorizontalAccuracy();
				float vAccuracy = c.getVerticalAccuracy();
				Coordinates greenwich = new Coordinates(0, 51, 0); 
				float disGreenwich = c.distance(greenwich);
				
				displayString = "Your Location method: " + locationMethod + "\n";
				displayString = displayString + "Latidude: " + latitude +"\n";
				displayString = displayString + "Longitude: " + longitude +"\n";
				displayString = displayString + "Altitude: " + altitude +"\n";
				displayString = displayString + "Horizontal Accuracy: " + hAccuracy +"\n";
				displayString = displayString + "Vertical Accuracy: " + vAccuracy +"\n";
				displayString = displayString + "Distance from Greenwich: 
								" + disGreenwich +" Meters";
			}
			else if(provider.getState() == LocationProvider.TEMPORARILY_UNAVAILABLE)  {
				displayString = "LBS Service is temporarily not available. 
									Please try agiain after some time";
			}
			
		} catch (LocationException e) {
			
			displayString = e.getMessage().toUpperCase()+" : LBS Service is not available for 
													you please contact your service provider.";
		
		}catch (InterruptedException e) {
			e.printStackTrace();
		}
		// LBS code ends here

Simple Location MIDlet "Where Am I?"

This MIDlet demonstrates the use of Location API to get present location parameters. The code segments in the above section are from this application. Download the complete application from salsa goodies.

Back | Tutorial Home | Next

More Tutorials

MIDP Basics
MIDP Gaming

This page is a part of a frames based web site. If you have landed on this page from a search engine click here to view the complete page.