back to j2megame.org

API Reference

Location API 2.0 (JSR 293)

See:
          Description

Packages
javax.microedition.location Contains the basic classes needed to request and get a location result.
javax.microedition.location.services Contains the classes and interfaces related to location based services.

 

Location API 2.0 (JSR 293)

Location API 2.0.

This document defines JSR 293, the Location API 2.0, version 2.0.

Author: Java Community Process / JSR 293 Expert Group (e-mail: jsr-293-comments@jcp.org)

Status: Final Release

Released: 2008-10-15

Copyright © 2003-2008 Nokia Corporation. All rights reserved.
Revision history
Version Published Description
2.0 2008-10-15 Final version

RESEARCH AND EVALUATION LICENSE

NOKIA CORPORATION IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE TERMS CONTAINED IN THIS LICENSE (“LICENSE”). PLEASE READ THE TERMS AND CONDITIONS OF THIS LICENSE CAREFULLY. BY ACCESSING OR USING THE SPECIFICATION YOU WILL BE BOUND BY THE TERMS OF THIS LICENSE.

JSR 293 Location API 2.0 (“Specification”)

Specification Lead: Nokia Corporation (“Specification Lead”)

Version: 2.0

Status: Final Release

Release: 2008-10-15

Copyright 2006-2008 Nokia Corporation. All rights reserved.

1. NOTICE; LIMITED LICENSE GRANTS

1.1 The Specification Lead hereby grants You a non-exclusive, non-transferable, worldwide, royalty-free, fully paid-up, limited license (without the right to sublicense) solely under intellectual property rights licensable by the Specification Lead to analyze and to use the Specification for research, evaluation, optimization and development purposes. In addition You may make a reasonable number of verbatim copies of this Specification in its entirety for Your private or internal use, as applicable, in accordance with the terms and conditions of this License.

1.2 No rights are granted under this License for internal deployment, the creation and/or distribution of implementations of the Specification for direct or indirect (including strategic) gain or advantage, the modification of the Specification (other than to the extent of Your fair use rights) or the distribution of the Specification or making the Specification available for 3rd parties.

1.3 Except as expressly set forth in this license, You acquire no right, title or interest in or to Specification or any other intellectual property licensable by the Specification Lead and no other rights are granted by implication, estoppel or otherwise. The Specification may only be used in accordance with the license terms set forth herein. This License will terminate immediately without notice from Specification Lead if You fail to comply with any provision of this License.

2. TRADEMARKS

2.1 Nokia is a registered trademark of Nokia Corporation. Nokia Corporation's product names are either trademarks or registered trademarks of Nokia Corporation. Your access to this Specification should not be construed as granting, by implication, estoppel or otherwise, any license or right to use any marks appearing in the Specification without the prior written consent of Nokia Corporation or Nokia's licensors. No right, title, or interest in or to any trademarks, service marks, or trade names of any third parties, is granted hereunder.

2.2 You shall not be allowed to remove any of the copyright statements or disclaimers or other proprietary notices contained in the Specification and You are obliged to include the copyright statement and the disclaimers, if any, in any copies of the Specification You make.

3. DISCLAIMER OF WARRANTIES

3.1 SUBJECT TO ANY STATUTORY WARRANTIES OR CONDITIONS WHICH CAN NOT BE EXCLUDED, THE SPECIFICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OR CONDITION OF ANY KIND EITHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. ALL WARRANTIES AND CONDITIONS, EXPRESS, IMPLIED, AND STATUTORY ARE HEREBY DISCLAIMED. THE ENTIRE RISK ARISING OUT OF OR RELATING TO THE USE OR PERFORMANCE OF THE SPECIFICATION REMAINS WITH YOU.

3.2 THE SPECIFICATION MAY INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. SPECIFICATION LEAD MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification.

4. LIMITATION OF LIABILITY

4.1 TO THE FULLEST EXTENT PERMITTED BY LAW, IN NO EVENT WILL THE SPECIFICATION LEAD OR ITS SUPPLIERS BE LIABLE FOR ANY LOST PROFITS, LOST SAVINGS, LOST REVENUE, LOST DATA, PROCUREMENT OF SUBSTITUE GOODS, OR FOR ANY DIRECT, INDIRECT, INCIDENTIAL, SPECIAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, EVEN IF THE SPECIFICATION LEAD OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES. IN ADDITION THE SPECIFICATION LEAD AND ITS SUPPLIERS WILL NOT BE LIABLE FOR ANY DAMAGES CLAIMED BY YOU BASED ON ANY THIRD PARTY CLAIM.

4.2 Some jurisdictions do not allow the exclusion of implied warranties, or the limitation for consequential damages, so Section 4.1 may not apply to You in whole, but in such case Section 4.1 will apply to You to the maximum extent permitted by applicable law.

5. EXPORT CONTROL

5.1 You shall follow all export control laws and regulations relating to Specification.

6. RESTRICTED RIGHTS LEGEND

6.1 Note to U.S. Government Users. The Specification is a “Commercial Items”, as that term is defined at 48 C.F.R. 2. 101, consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation”, as such terms are used in 48 C.F.R. 12.212 or 48 C.F.R. 227.7202, as applicable. Consistent with 48 C.F.R. 12.212 or 48 C.F.R. 227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software Documentation are being licensed to U.S. Government end users a) only as Commercial Items and b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States.


Preface

This specification was produced by the JSR 293 Expert Group in the Java Community Process (JCP). For more information, visit the JSR 293 web page at http://www.jcp.org/en/jsr/detail?id=293.

Contributors

The Expert Group consisted of representatives from the following companies and individuals:

Comments

Your comments about this specification are welcome. Please send them by electronic mail to the following address:

<>

Document conventions

The key words must, must not, required, shall, shall not, should, should not, recommended, may and optional in this specification are to be interpreted as described in RFC 2119 [Keywords]. The key words are typographically different in this specification than as described in the RFC, but they are used in the same meaning.

Monospaced type is used to denote literal text, such as class names and code samples.

Unicode characters are expressed in the U+NNNN notation, where NNNN denotes a 16-bit hexadecimal code point.

Mathematical notation for defining ranges of floating point numbers is used as defined below:

Table 1. Mathematical notation for ranges

[a,b] a closed range from value a to value b with the end-points a and b included in the range
(a,b) an open range from value a to value b with the end-points a and b not included in the range
[a,b) a half-open range from value a to value b with the end-point a included and end-point b not included in the range
(a,b] a half-open range from value a to value b with the end-point a not included and end-point b included in the range


EBNF notation is used to define syntax elements [EBNF].


Location API 2.0

Overview

Introduction

JSR 179 ([JSR179]) specification defined a Java ME Optional Package that enabled mobile location-based applications for resource limited devices (referred to as 'terminals' in the following). The API was designed to be a compact and generic API that produces information about the present geographic location of the terminal to Java applications. JSR 179 covers obtaining information about the present geographic location and orientation of the terminal and accessing a database of known landmarks stored in the terminal.

JSR 293 Location API 2.0 for Java ME extends JSR 179 Location API. This means that JSR 179 specification is part of the JSR 293 specification. Therefore applications written for Location API are upwards compatible with Location API 2.0 and will work without any changes in the Location API 2.0 compliant terminals. In addition to minor clarifications to Location API, the version 2.0 adds several new features like geocoding, map and navigation services and landmark exchange to the API. These features are described in more detail later in this overview.

System requirements

Location API 2.0 is intended for Java Micro Edition implementations with the Connected, Limited Device Configuration [CLDC], version 1.1 or later, or the Connected Device Configuration [CDC], version 1.0.1 or later.

System properties

To enable applications to test for the presence of the Location API 2.0 and its version during runtime, a system property microedition.location.version is defined. For fully compliant implementations of this specification the value must be 2.0.

System property microedition.location.orientation indicates if the API implementation supports the compass azimuth of the terminal orientation. If the API implementation does support orientation, the value of this system property must be "true". If orientation is not supported, the value must be "false".

System property microedition.location.areamonitoring indicates if area monitoring feature is supported. If some location method is able to support area monitoring, the value of this system property must be "true". If area monitoring is not supported by any of the location methods, the value must be "false".

New features in Location API 2.0

The new features added to Location API 2.0 include:

The following chapters describe these features in more details.

Service interfaces

As location based applications are getting more popular, their feature set is getting richer. Therefore the number of location based service is growing. For this reason, the Location API 2.0 provides interfaces for main location based services and enabled applications to take advantage of these services. These location based services are map, navigation and geocoding services.

For further details of the service provider interfaces, see package description of javax.microedition.location.services package.

Landmark exchange

In Location API [JSR179] landmarks are stored locally to a landmark store on the terminal. Therefore landmarks can only be edited on that terminal. As the location based applications are getting more popular, there is a need to share landmarks or move landmarks from one terminal into another. For these reasons this Location API 2.0 defines mechanisms for exporting landmarks from a terminal and importing landmarks into a terminal.

More information about landmark exchange formats in Appendix C.

Landmark categories

In Location API [JSR179] landmarks can be assigned into categories. One landmark can belong into several categories and the Location API provides a mechanism to list the categories that a landmark belongs to. Since landmark categories are information that is shown to the user, they should be localized.

Location API 2.0 provides a mechanism to import and export landmarks. With this mechanism the landmark categories get a more important role. Therefore this API will define a set of global landmark categories that must be present in all terminals that support version 2.0 of the Location API. The names of the global landmark categories must be localized.

The detailed descriptions of global landmark categories can be found from the description of LandmarkStore class.

Mandatory and optional features

This API contains some options whose availability depends on the supported location methods and device implementations. These options are needed to allow differences in supported location methods. Implementations should support all features that are possible with the location methods that are supported.

In general, every implementation must contain all the classes, interfaces and methods as defined in this specification. Those features that are optional to support have a defined behaviour in the case the feature is not supported by the implementation.

Mandatory features

Mandatory API features are:

Conditionally mandatory features

Conditionally mandatory features that must be implemented if they are supported by location method:

Conditionally mandatory features that must be implemented if the terminal has the hardware capabilities:

Optional features

Optional features whose availability depends on the landmark store implementation of the terminal and its possible relation to landmark stores shared with native applications:

Optional features whose availability depends on the API implementation on the terminal:


Related documentation

[CDC] Connected Device Configuration Specification, Version 1.1. Java Community Process. August, 2005. http://www.jcp.org/en/jsr/detail?id=218.

[CLDC] Connected, Limited Device Configuration Specification, Version 1.1. Java Community Process. March, 2003. http://www.jcp.org/en/jsr/detail?id=139.

[EBNF] Information technology - Syntactic metalanguage - Extended BNF. International Organization for Standardization. 1996. http://www.iso.org.

[EPSG] EPSG Geodetic Parameter Dataset. OGP Surveying & Positioning Committee. 2007. http://www.epsg.org/.

[ISO3166] Codes for the representation of names of countries and their subdivisions -- Part 1: Country codes. International Organization for Standardization. 1997. http://www.iso.org.

[JSR179] Location API for Java ME. Java Community Process. March, 2006. http://www.jcp.org/en/jsr/detail?id=179.

[Keywords] S. Bradner. Key Words for use in RFCs to Indicate Requirement Levels. RFC 2119. March, 1997. http://www.ietf.org/rfc/rfc2119.txt?number=2119.

[MIDP2] Mobile Information Device Profile, version 2.1. Java Community Process. June, 2006. http://www.jcp.org/en/jsr/detail?id=118.

[MLP] TS 101 Mobile Location Protocol Specification, version 3.0. Open Mobile Alliance, Location Working Group. June, 2002. http://www.openmobilealliance.com/tech/affiliates/lif/lifindex.html.

[NMEA] NMEA 0183 Interface standard, version 3.01. The National Marine Electronics Association. January, 2002. http://www.nmea.org/pub/0183/index.html.

[OpenLS] OpenGIS Location Service. Open Geospatial Consortium, Inc. . May, 2005. http://www.opengeospatial.org/standards/olscore.

[RFC4589] Location Types Registry. RFC 4589. July, 2006. http://www.ietf.org/rfc/rfc4589.txt.

[RFC4646] Tags for Identifying Languages. RFC 4646. September, 2006. http://www.ietf.org/rfc/rfc4646.txt.

[RFC4647] Matching of Language Tags. RFC 4647. September, 2006. http://www.ietf.org/rfc/rfc4647.txt.

[WGS84] NIMA TR8350.2 World Geodetic System 1984. It's definition and Relationships with Local Geodetic Systems. U.S. Department of Defence. January, 2000. http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf.

[XMLSchema1] XML Schema Part 1: Structures Second Edition. W3C Recommendation. October, 2004. http://www.w3.org/TR/xmlschema-1/.

[XMLSchema2] XML Schema Part 2: Datatypes Second Edition. W3C Recommendation. October, 2004. http://www.w3.org/TR/xmlschema-2/.


Glossary

This section defines terms used in the specification.

Assisted

Implies that the other party provides some information assisting determining the location to the party that does the final calculation. For example, for a terminal based method ’assisted’ means that the network provides some assistance information. See ’terminal based’ and ’network based’.

Category

Category is used to group Landmarks that are of similar type to the end user, e.g. restaurants, museums, etc. Category has an identifying unique name that identifies the category to the end user.

Coordinates

The geographical coordinates (latitude, longitude, altitude) that identify an exact location point. In this API, these are encapsulated in instances of the Coordinates class.

Course

Course made good, i.e. direction of the velocity vector, relative to true north.

Geocoding

Geocoding is the process of converting street addresses into geographic coordinates

GIS

Geographic Information System

GPS

Global Positioning System

Landmark

A known geographical location that has a name and a category associated with it. The name is a textual name that identifies that location for the end user and the category provides a grouping of similar landmarks based on some property that is meaningful to the end user. In this API, often refers to the class Landmark. The landmarks are usually stored in a local database in the terminal that is represented by the LandmarkStore class in this API.

Location

Geographical location. In this API, often refers to the class Location that encodes the geographical coordinates, their accuracy, the current course and speed of the terminal (if available), textual address information for the location (if available) and the timestamp when the location measurement was made.

Network based

A location method is network based if the final calculation that gives the location result is performed in the network.

Qualified Coordinates

The geographical coordinates (latitude, longitude, altitude) that identify a location combined with their accuracy information. These identify a geographical location with some uncertainty of the measurement represented by the accuracy values. In this API, these are encapsulated in instances of the QualifiedCoordinates class.

Reverse Geocoding

Reverse Geocoding is the process of converting geographic coordinates into a street address

Route

Consists of two or more waypoints combined in a course of travel.

Terminal based

A location method is terminal based if the final calculation that gives the location result is performed in the terminal.

Waypoint

Location or landmark that can be stored to be recalled and used at a later time for navigation purposes.


Appendices

Appendix A. Security of Location API 2.0

Appendix B. Code examples

Appendix C. Landmark exchange formats

Appendix D. Service provider implementation notes



Copyright © 2003-2008 Nokia Corporation. All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.