Implementation of the Tourist Route MIDlet

Application Architecture

In the TouristRoute example MIDlet, all the UI classes are included in the com.nokia.example.location.tourist.ui package. Model classes can be found from the com.nokia.example.location.tourist.model package. In this example, only the classes in the model package use Location API functionality. When using the TouristRoute MIDlet to get acquainted with the Location API, the model layer classes might be the most interesting ones to take a look at. The UI layer classes only contain the MIDlet-specific UI implementation and might not help much in learning how to use the Location API. In addition, command controller logic is coded in the UI classes. The figure below shows TouristRoute example's classes and relationships.

The model layer classes and interfaces include the following tasks:

• ControlPoints handles all landmark store-related operations.

• TouristData listens for events through LocationListener and ProximityListener and handles data update on the viewer class TouristUI

• ProviderStatusListener is an interface that is used to deliver the location provider selection notification. In addition, this interface is used to deliver the information that LocationProvider has successfully started to receive location updates (for example, from a GPS module). The TouristRoute MIDlet listens for events through this interface.

• The ConfigurationProvider class handles LocationProvider selection in the application startup stage. After a location provider is selected, a notification event is sent back to MIDlet through the ProviderSelectedListener interface. In addition, orientation support checking and Orientation class access in the Location API belongs to this class.

Startup Sequence

TouristRoute example MIDlet startup performs an automatic location provider search. The MIDlet use can begin after the location provider is found and the MIDlet is capable of receiving a location update event. The purpose of this section is to clarify the TouristRoute example MIDlet's startup sequence.

The use of a network-based location provider may require the user to pay a fee. TouristRoute first tries to find a free location provider from a set of predefined location providers. If no free location providers are available, TouristRoute confirms with the end user whether (s)he wants to use a non-free service. The TouristRoute MIDlet uses predefined cost Criteria in searching for location providers.

The sequence diagram in below figure demonstrates the idea of how the TouristRoute MIDlet searches location providers. At first, the MIDlet looks for free location providers. If none are found, the MIDlet asks the user for permission to continue the search with non-free providers. If a cost-free location provider (for example, a GPS module over a Bluetooth connection) is found, the location provider search will end. When a location provider is found and selected, the example MIDlet receives providerSelectedEvent().

At this point, the MIDlet registers to listen for events from the selected location provider. Especially when using a GPS module as a location provider, the first position calculation may take a while. That is why the first locationUpdated() event arrival on the TouristData class may take a while. When the first locationUpdated() event arrives, the firstLocationUpdateEvent() event is sent to the TouristMIDlet class. At this stage the application UI (TouristUI) is set to visible.