21 JSR 179 and 293: Location API Support

21.1 Setting the Emulator's Location at Runtime

You can specify the simulated location of the emulator while it is running. To do this, choose Device > Location. This raises the external events generator with the Location tab selected.

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 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:

<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 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. In this demo we get 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 "Section 12.1, "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.

1. Open and run the CityGuide project. In the emulator, launch the CityGuide MIDlet. Click Load to view the map page.

   
   Description of the illustration cityguide.gif
   
   

2. In the emulator, choose Device > Location. On the Location tab, click the Browse button. Select the following event file: installdir\apps\CityGuide\citywalk.xml.

   The player buttons at the bottom of the window are now active. Press the green play button (right-pointing triangle) to run the script.

3. The display shows four types of landmarks: restaurants, museums, shops, and theaters.

   To adjust the landmark display, open the soft menu and choose the Settings command. Use the navigation keys to highlight a category, then use Select to check or uncheck an item.

   When you are near a landmark (shown highlighted on the map), open the soft menu and choose the Detail command to see more information.

   
   Description of the illustration location-settings.gif
   
   

21.3 Running the CityGuide2_0 Sample Project

The City Guide2_0 example works much like the CityGuide sample project. The difference is that it implements the Landmark export function, which exports landmarks using an MMS text message.

1. Open and run the CityGuide2_0 project. In the emulator, launch the CityGuide MIDlet. Click Load to view the map page.

2. In the emulator, choose Device > Location. On the Location tab, click the Browse button. Select the following event file:.

   installdir\apps\CityGuide2_0\citywalk.xml

   The player buttons at the bottom of the window are now active. Press the green play button (right-pointing triangle) to run the script.

3. The display shows five types of landmarks: gc_public_service, restaurants, museums, shops, and theaters. gc_public_service indicates wireless service is detected and landmark export is possible.

   When running the script you can see the wireless service detected between 28 seconds and one minute twenty seconds.

4. Run the CityGuide2_0 project in a second emulator. At the introduction page, press the Import soft button. The application displays "Waiting for MMS".

5. In the first emulator, open the menu and choose option 3, Export. Set the phone number to point to the second emulator.

   
   Description of the illustration cityguide-export.gif
   
   

   From the menu, select option 2, Send.

6. In the second emulator, the message changes to Importing MMS and you see a progress bar as the transmission completes.