21 JSR 179: Location API Support

JSR 179: Location API for J2ME gives applications the opportunity to use a device's location capabilities. For example, some devices include Global Positioning System (GPS) hardware. Other devices might be able to receive location information from the wireless network. The Location API provides a standard interface to location information, regardless of the underlying technique.

In the Location API, a location provider encapsulates a positioning method and supplies information about the device's location. The application requests a provider by specifying required criteria, such as the desired accuracy and response time. If an appropriate implementation is available, then the application can use it to obtain information about the device's physical location.

Oracle Java ME SDK 8 includes a simulated location provider. You can use the emulator's External Events Generator to specify where the emulator should think it is located. In addition, you can configure the properties of the provider itself, and you can manage a database of landmarks.

Setting the Emulator's Location at Runtime

To specify the simulated location of the emulator while it is running:

In the emulator, open the Tools menu and select External Events Generator. Click the Location tab.
Under the Location group, specify values for latitude, longitude, altitude, speed, and course. Applications that use the Location API can retrieve these values as the location of the emulator.

For more elaborate testing, you can set up a location script that describes motion over time. Location scripts are XML files that consist of a list of locations, called waypoints, and associated times. Oracle Java ME SDK 8 determines the current location of the emulator by interpolating between the points in the location script. Here, for example, is a simple location script that specifies a starting point (time="0") and moves to a new point in 10 seconds (time="10000"):

Example 21-1 Location Script Example

<waypoints>
  <waypoint time="0"
            latitude="14" longitude="50" altitude="310" />
  <waypoint time="10000"
            latitude="14.5" longitude="50.1" altitude="215" />
</waypoints>

The altitude measurement is in meters, and the time values are in milliseconds.

Use a text editor to create your location script. You can point the External Events Generator to this script by clicking Browse next to the Script field. Below the Script field are controls for playing, pausing, stopping, and moving to the beginning and end of the location script. You can also drag the time slider to a particular point.

Some devices are also capable of measuring their orientation. To make this kind of information available to your application, change the State field in the Orientation group to Supported, and specify values for azimuth, pitch, and roll. The Magnetic Orientation check box defines whether the azimuth and pitch measurements are relative to the Earth's magnetic field or relative to true north and gravity.

To test how your application handles unexpected conditions, try changing the State field in the Location Provider group to Temporarily Unavailable or Out of Service. When your application attempts to retrieve the emulator's location, an exception is thrown, and you can see how your application responds.