Finding Your Way - Beginning Java ME Platform - page 490

• timeout : Specifies how late a location may be after the interval elapses
• maximumAge : Specifies how old a location result is permitted to be when the event is
set (in seconds)
In a similar vein, your application can receive notification when the device is near to
a specific location by adding a ProximityListener using the addProximityListener method.
When you do this, you specify the instance that implements the ProximityListener inter-
face, the coordinates of the desired location, and a radius in meters around the desired
location that defines the region of proximity. Note, however, that while you can have
multiple proximity notifications with a single LocationProvider , you can only have a
single LocationListener .
Using the Location API to Manage Landmarks
The Location API includes two classes that let location-aware applications interact
with each other through a common store: Landmark and LandmarkStore . Any LBS-enabled
application with security privilege may add to this store, as well as view and modify
elements in this store. These two classes enable you to add a landmark in one applica-
tion—say, a travel guide—and access the same landmark from another application,
such as a turn-by-turn navigation application.
As the names suggest, the LandmarkStore contains representations of Landmark objects.
The LandmarkStore is persistent, although the actual implementation isn't specified; it
may keep its records in an MIDP record store in flash memory or use another storage
scheme altogether.
The Location API requires any implementation to have at least one LandmarkStore ,
called the default LandmarkStore , although the implementation may support additional
stores, which you access by name much like an MIDP record store. To access a store, you
must first get an instance of LandmarkStore , which you do by invoking its static method
getInstance and passing the name of the store you seek (or null for the default store).
You can obtain a list of stores by invoking the LandmarkStore.listLandmarkStores method,
which returns an array of String s containing the name of each store on the device. The
LandmarkStore also provides the static methods createLandmarkStore and
deleteLandmarkStore for creating and deleting a store.
Like the PIM package I showed you in Chapter 7, the Location API supports cate-
gories for the LocationStore ; a category is simply a String attached to entries in the store,
letting users group related items by that String (such as “Work” or “Vacation”). You use
the following methods to interact with categories in a store:
• getCategories : Enumerates the categories in a store, which returns an Enumeration
• addCategory : Adds a category
• deleteCategory : Deletes a category while retaining the records in the category