|
back to j2megame.org | |||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||
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. |
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.| Version | Published | Description |
|---|---|---|
| 2.0 | 2008-10-15 | Final version |
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.
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.
The Expert Group consisted of representatives from the following companies and individuals:
China Mobile Communications Co. Ltd
Ericsson AB
Gazineu, Daniel
IBM
Logica Cmg Wireless Networks
Martini, Alexandre
Motorola
Navicore Ltd
Navteq LLC
Networks In Motion, Inc
Nokia Corporation
Orange France SA
Research In Motion, LTD (RIM)
Samsung Electronics Corporation
SBC
SiRF Technology Holdings, Inc
Sony Ericsson Mobile Communications AB
Sprint
Sun Microsystems, Inc.
Telecom Italia
University of South Florida
Your comments about this specification are welcome. Please send them by electronic mail to the following address:
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].
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.
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.
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".
The new features added to Location API 2.0 include:
Interfaces for accessing location based service like map, navigation and geocoding services
A mechanism for exchanging (importing and exporting) landmarks
A set of global landmark categories that are localized and present in all Location API 2.0 compliant terminals
The following chapters describe these features in more details.
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.
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.
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.
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 API features are:
Provide latitude and longitude coordinates and their accuracy
Provide timestamp of the location measurement
Support one (default) LandmarkStore
for storing landmarks
Support all the fields defined in the
Landmark class
Support for global landmark categories
Support for one landmark exchange format and importing and exporting landmarks
The landmark exchange format must support all the fields defined
in the Landmark class
Conditionally mandatory features that must be implemented if they are supported by location method:
Provide altitude information
Provide accuracy of altitude
Provide course and speed information
Provide textual address information related to the location
Provide proximity monitoring events
Provide area monitoring events
Conditionally mandatory features that must be implemented if the terminal has the hardware capabilities:
Provide the compass azimuth of the terminal orientation, if the terminal has a compass
Optional features whose availability depends on the landmark store implementation of the terminal and its possible relation to landmark stores shared with native applications:
Creating and deleting landmark stores, including private landmark stores
Adding, removing and renaming landmark categories
Adding and removing LandmarkStoreListener
Optional features whose availability depends on the API implementation on the terminal:
Support for geocoding service provider
Support for map service provider
Support for navigation service provider
[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] 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.
[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/.
This section defines terms used in the specification.
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 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.
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 made good, i.e. direction of the velocity vector, relative to true north.
Geocoding is the process of converting street addresses into geographic coordinates
Geographic Information System
Global Positioning System
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.
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.
A location method is network based if the final calculation that gives the location result is performed in the network.
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 is the process of converting geographic coordinates into a street address
Consists of two or more waypoints combined in a course of travel.
A location method is terminal based if the final calculation that gives the location result is performed in the terminal.
Location or landmark that can be stored to be recalled and used at a later time for navigation purposes.
Appendix A. Security of Location API 2.0
Appendix B. Code examples
Appendix C. Landmark exchange formats
Appendix D. Service provider implementation notes
|
||||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||