V 1.0
TECHNICAL ARTICLE
Copyright © 2008, Motorola, Inc. All rights reserved. This documentation may be printed and copied solely for use in developing
products for Motorola products. In addition, two (2) copies of this documentation may be made for archival and backup purposes.
Except for the foregoing, no part of this documentation may be reproduced or transmitted in any form or by any means or used to
make any derivative work (such as translation, transformation, or adaptation) without express written consent from Motorola, Inc.
Motorola reserves the right to make changes without notice to any products or services described herein. "Typical" parameters,
which may be provided in Motorola Data sheets and/or specifications, can and do vary in different applications and actual
performance may vary. Customer's technical experts will validate all "Typicals" for each customer application.
Motorola makes no warranty in regard to the products or services contained herein. Implied warranties, including without limitation,
the implied warranties of merchantability and fitness for a particular purpose, are given only if specifically required by applicable law.
Otherwise, they are specifically excluded.
No warranty is made as to coverage, availability, or grade of service provided by the products or services, whether through a service
provider or otherwise. No warranty is made that the software will meet your requirements or will work in combination with any
hardware or application software products provided by third parties, that the operation of the software products will be uninterrupted
or error free, or that all defects in the software products will be corrected.
In no event shall Motorola be liable, whether in contract or tort (including negligence), for any damages resulting from use of a
product or service described herein, or for any indirect, incidental, special or consequential damages of any kind, or loss of revenue
or profits, loss of business, loss of information or data, or other financial loss arising out of or in connection with the ability or inability
to use the Products, to the full extent these damages may be disclaimed by law.
Some states and other jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, or limitation on
the length of an implied warranty, therefore the above limitations or exclusions may not apply to you.
This warranty gives you specific legal rights, and you may also have other rights, which vary from jurisdiction to jurisdiction.
Motorola products or services are not designed, intended, or authorized for use as components in systems intended for surgical
implant into the body, or other applications intended to support or sustain life, or for any other application in which the failure of the
Motorola product or service could create a situation where personal injury or death may occur.
Should the buyer purchase or use Motorola products or services for any such unintended or unauthorized application, the buyer
shall release, indemnify and hold Motorola and its officers, employees, subsidiaries, affiliates, and distributors harmless against all
claims, costs, damages, and expenses, and reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury
or death associated with such unintended or unauthorized use, even if such claim alleges that Motorola was negligent regarding the
designing or manufacturing of the product or service.
Motorola recommends that if you are not the author or creator of the graphics, video, or sound, you obtain sufficient license rights,
including the rights under all patents, trademarks, trade names, copyrights, and other third party proprietary rights.
If this documentation is provided on compact disc, the other software and documentation on the compact disc are subject to the
license agreement accompanying the compact disc.
Location API JSR-179
Version 1.0
April 2008
For the latest version of this document, visit http://developer.motorola.com
Motorola, Inc.
http://www.motorola.com
Contents
Introduction to the Java ME Location API .................................................................................................... 3
Location Technologies............................................................................................................. 3
Developing Applications using Location API.......................................................................... 4
Using Location API Notes ....................................................................................................... 8
Summary .................................................................................................................................. 9
References 10
Permissions used in JSR-179 ....................................................................................................................... 10
Location Technologies
Location information can be expressed in spatial terms. A spatial location is expressed in the latitude-
longitude-altitude coordinate system. Latitude is expressed as 0-90 degrees north or south of the equator,
and longitude is 0-180 degrees east or west of the prime meridian, which passes through Greenwich,
England. Altitude is expressed in meters above sea level.
There are several methods to determine the location of a mobile device. These methods may be handset-
dependent or network-dependent. So you should know your handset and ask your carrier about the
location method that works with your particular handset. Mobile location methods include both network
based and mobile device based locations.
1 Network based location
Cell-ID method. This method identifies the location of the handset by the Base Transceiver
Station (BTS) that the handset is communicating with and the location of that BTS. The handset
can be at any position in the cell. The precision is decided by the size of the cell, and it can be
quite inaccurate.
E-OTD (Enhanced-Observed Time Difference)/U-TDOA (Uplink Time Difference of
Arrival)/OTDOA (Observed Time Difference of Arrival) method etc. These methods use the time
difference to locate the mobile device; the precision depends on the precision for the system time
of the mobile network.
2 Mobile device based location. GPS (Global Positioning System) is potentially the most accurate
method, but it has some drawbacks: It consumes a lot of battery power while in use. It also suffers
from canyon environments, such as in cities where satellite visibility is intermittent and the GPS
signals are blocked by buildings and there are not enough satellites signals to estimate the positions
of the user.
A-GPS (Assisted Global Positioning Systems). The mobile device must be equipped with a GPS
receiver. The network uses the cell that the mobile device communicates with to locate the GPS
satellite above the cell, and provides this information to the mobile device. The mobile device
uses such information to narrow down the searching scope and shorten the searching time so
that it can locate the satellite more quickly.
Autonomous GPS. The mobile device has a full function GPS receiver. The location information
is obtained by the mobile device itself. It may, however, take some time to get an initial fix on the
visible satellites.
GPS A-GPS: both the Both the network and the Medium Limited in canyon 5-40
network and the mobile device need to be environments
mobile device are modified
needed to do the
calculation
NOTE: * The expense is for modifications to enable location support. These costs could to the developer
and/or to the network operator who wants to provide location support.
For the handset-independent location method, there are different mobile devices on the market that you
can use.
• Use handsets which have a built-in GPS chipset in them. The handset must support the Location API
JSR-179. In this case, you can use the Location API. This article will discuss this method and the
Location APIs more in the following section.
• For handsets which have no built-in GPS chipset, you can use a serial or Bluetooth connection with a
GPS module. This article does not discuss this case. Please refer to the “Introduction to GPS” article
which is listed in the References section at the end of this article.
Location Represents the standard set of basic location The implementation has a limit for
information. This includes the time-stamped the maximum number of location
coordinates, accuracy, speed, course, etc. read requests that can be sent
simultaneously.
ProximityListener Receives updates based on terminal crossing The implementation has a limit for
into a defined radius around a coordinate. the maximum number of proximity
listeners that can be added
simultaneously.
Landmark The Landmark class represents a landmark, The implementation has limitations
such as a known location with a name (such as such as maximum number of
a monument). landmark store categories,
landmarks in landmark store, etc.
LandmarkStore The LandmarkStore class provides methods to The implementation may only
store, delete and retrieve landmarks from a support default landmark store and
persistent landmark store. not support creating and deleting
LandmarkStore methods.
The Location API for J2ME (JSR-179) provides a standard interface to access location based information.
The classes are in the optional package javax.microedition.location. The three main features of
the Location API are:
• Obtaining information about the location of a device
• The possibility to create, edit, store, and retrieve landmarks
• The possibility to obtain the orientation of a device.(The implementation of the device may not support
this feature.)
Table 2, shown previously, gives the main classes and their brief description.
......
try {
Criteria crit = new Criteria();
crit.setCostAllowed(true); //default value
crit.setSpeedAndCourseRequired(true);
crit.setHorizontalAccuracy(500);
crit.setAltitudeRequired(true);
crit.setPreferredPowerConsumption(Criteria.POWER_USAGE_LOW);
// Instantiate a location provider with specified criteria
LocationProvider locp = LocationProvider.getInstance(crit);
// Get a location fix for 30 seconds timeout
Location loc = locp.getLocation(30);
} catch (LocationException e) {
// location unavailable
System.out.println(e.toString());
}
......
if (loc.isValid()) {
float course = loc.getCourse();
float speed = loc.getSpeed();
Coordinates qc = loc.getQualifiedCoordinates();
if (qc!=null) {
double latitude = qc.getLatitude();
double longitude = qc.getLongitude();
float altitude = qc.getAltitude();
}
}
else
System.out.println("location invalid");
The developer can set LocationListener to the LocationProvider using the method shown next.
LocationProvider.setLocationListener(LocationListener?listener, int interval,
int timeout, int maxAge)
Next is an example of using LandmarkStore to get all the landmarks stored in it.
Summary
There are many choices to implement a location application. The Location API provides the ability to get
the location information of the mobile device. The Location API JSR-179 is convenient to use and it is a
good choice to implement a location application on the mobile phones which support Java ME.
LocationProvider.getLocation(),
javax.microedition.location.Location LocationProvider.setLocationListener(),
LocationProvider.getLastKnownLocation()
javax.microedition.location.Orientation Orientation.getOrientation()
javax.microedition.location.ProximityListener LocationProvider.addProximityListener()
LandmarkStore.addLandmark(), LandmarkStore.deleteLandmark(),
javax.microedition.location.LandmarkStore.write LandmarkStore.removeLandmarkFromCategory(),
LandmarkStore.updateLandmark()
LandmarkStore.createLandmarkStore(),
javax.microedition.location.LandmarkStore.management
LandmarkStore.deleteLandmarkStore()