21 JSR 179: Location API Support

The JSR 179 Location API 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, the application can use it to obtain information about the device's physical location.

The Oracle Java ME SDK 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.

21.1 Setting the Emulator's Location at Runtime

You can specify the simulated location of the emulator while it is running. In the emulator, click the Tools menu and select External Events Generator. Click the Location tab.

In the Location area of the tab, you can fill in values for the 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 consisting of a list of locations, called waypoints, and associated times. The Oracle Java ME SDK 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 ten seconds:

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>

Figure 21-1 External Events Generator Location Tab

Description of "Figure 21-1 External Events Generator Location Tab"

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

Use a text editor to create your location script. You can load it into the external event window by pressing the Browse button next to the Script field. Immediately below 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 box to Supported and fill in values for azimuth, pitch, and roll. The Magnetic Orientation check box indicates 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 box 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.

21.2 Running the CityGuide Sample Project

CityGuide demonstrates how to use the Location API (JSR 179). It shows a walker's current position superimposed on a city map. The walker moves around the city and landmarks are highlighted and identified as the walker approaches. This demo gets the walker's location from an XML script named citywalk.xml (the event file) that submits the device location information.

Because location prompts occur frequently, it is best to run this demonstration in manufacturer (trusted) mode, as explained in the topic "Security Domains“"Security Domains." In the user interface, right-click on your project and select the Running category. Select Specify the Security Domain, and select manufacturer or maximum.

Open and run the CityGuide project. In the emulator, launch the CityGuide MIDlet. The map page opens.
By default the display shows icons for four types of landmarks: restaurants, museums, shops, and theaters.

To adjust the landmark display (this is optional), open the soft menu and select the Settings command. Use the navigation keys to highlight a category, then use Select to check or uncheck an item. In the default skin, the item is selected when the square is filled with white.

Figure 21-2 The Location Settings Dialog Box

Description of "Figure 21-2 The Location Settings Dialog Box"
In the emulator, click the Tools menu and select External Events Generator. Click the Location tab, then click the Browse button. Select the event file from the directory containing the Citywalk application.

The player buttons at the bottom of the window are now active. Press the green play button (right-pointing triangle) to run the script.
When you are near a landmark its name appears at the top of the map. Open the soft menu and select the Detail command to see more information.

Figure 21-3 The Landmark Detail Screen

Description of "Figure 21-3 The Landmark Detail Screen"