Class and interface description

The javax.microedition.location package is supported as specified in section Feature description apart from the following considerations:

LocationProvider

The LocationProvider class uses the native Location acquisition API.

The default timeout for getLocation is set to:

  • 2 * "average time to first fix", timeout >= 15s.

The “average time to first fix” value is retrieved from the native API for the used location technology.

The default values for setLocationListener are set to:

  • interval = 1.25 * TTF (if terminal-based), 4 * TTF (if network-based)

  • timeout = MIN(2 * TTF, interval)

  • maxAge = 0.5 * interval

The “average time to next fix” (Time-to-Fix, TTF) value is retrieved from the native API for the used location technology.

State changes to and from AVAILABLE and TEMPORARILY_UNAVAILABLE are delayed to reduce the number of changes:

  • From AVAILABLE to TEMPORARILY_UNAVAILABLE = 5 seconds

  • From TEMPORARILY_UNAVAILABLE to AVAILABLE = 2 seconds

LandmarkStore

The LandmarkStore implementation uses the native Landmark APIs. Stores are always created on the default drive. The default drive is set by the native API and is the phone’s internal drive, which is non-removable. Store names are case insensitive.

Special syntax store name (x:), where x is a drive letter can be used, for example:

LandmarkStore.getInstance("My store (c:)")

This syntax is used in listLandmarkStores for stores that are found on other drives than the default drive and is also supported in getInstance and deleteLandmarkStore.

Maximum string lengths:

  • Landmark name = 255

  • Category name = 124

  • Description = 4096

For createLandmarkStore, the following considerations apply:

  • Drive cannot be specified using store name (x:), landmark stores are always created on the default drive.

  • Case is preserved for store names.

  • IllegalArgumentException is thrown if bad characters are used in the name (for example ‘:’).

  • Created stores have predefined categories. This is done by the native implementation and it also decides the specific categories created.

For getLandmarks, the following apply:

  • Special search features:

    • * and ? are wildcards.

    • Empty string “” as category name finds uncategorized landmarks.

  • Examples:

    • getLandmarks("", "f*Bar") matches all uncategorized landmarks with names like “fooBar”, “foooBar”, “fBar” etc. (* matches 0 or more characters).

    • getLandmarks("fooBa?", null) matches all landmarks in categories “fooBar”, “fooBaz” etc. (? matches exactly 1 character).

In S60 3rd edition FP 1 and later, the performance of landmarks has been improved to give developers a possibility to optimize their Location-Based Java applications. Retrieving landmarks from the store has been optimized by initializing only minimal landmark attributes depending of which variant of LandmarkStore.getLandmarks() is used:

  • LandmarkStore.getLandmarks() and LandmarkStore.getLandmarks( String category, String name ):

    • Initializes the names of the returned landmarks. It is recommended that this attribute is retrieved first from the returned landmarks if needed.

    • The description, coordinates and address information of the landmarks are read from the store when accessed by the client

  • LandmarkStore.getLandmarks( String category, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude ):

    • Initializes the names and the position information of the returned landmarks. It is recommended that these attributes are retrieved first from the returned landmarks if needed.

    • Description and address information are read from the store when az§ccessed by the client.

Enumerating the returned landmarks is now a very fast operation but the data of the landmarks should be accessed only when it is really needed by the client, that is, it is not recommended to enumerate all landmarks and get all landmark attributes from each landmark. Depending on the number of address information fields in the landmarks, Landmark.getAddressInfo() may be a slow operation if performed for huge amount of landmarks. Therefore it should be used only when necessary. Getting the name, description and coordinates of a landmark is quite efficient in most cases.

AddressInfo

The maximum string length for the address fields is 255.

Coordinates

The distance and azimuthTo methods of the Coordinates class call the native Location API. This means that the algorithm used is the same as in the native API.

Orientation

The Orientation implementation accesses the Tilt Compensation plug-in by using the native sensor framework to fetch the azimuth (horizontal pointing direction) data. Pitch and Roll data are not supported.

If the sensor framework is able to determine the azimuth data, getOrientation returns the orientation object with accurate azimuth value. If the azimuth data can not be determined, the call returns null.

The orientation implementation checks for the compass calibration, if the compass is not calibrated the method getOrientation returns null. For instructions on calibrating the compass, see Nokia 6210 Navigator support at Nokia web site.

Pitch and Roll data values default to Float.NaN.

© Nokia 2009.