API JSR 179

Location APIfor Java™ 2 Micro Edition Version 1.0 JSR-179 Expert Group [email protected] Java Community Process ii Copyright Notice and Disclaimers Location API Specification (“Specification”) Version: 1.0 Status: Final Release Specification Lead: Nokia Corporation (“Specification Lead”) Release: 2003-05-14 Copyright © 2003 Nokia Corporation All rights reserved. NOTICE; LIMITED LICENSE GRANTS Specification Lead hereby grants you a fully-paid, non-exclusive, non-transferable, worldwide, limited license (without the right to sublicense), under the Specification Lead’s applicable intellectual property rights to view, download, use and reproduce the Specification only for the purpose of internal evaluation, which shall be understood to include developing applications intended to run on an implementation of the Specification provided that such applications do not themselves implement any portion(s) of the Specification. The Specification contains proprietary information of the Specification Lead and may only be used in accordance with the license terms set forth herein. Specification Lead also grants you a perpetual, non-exclusive, worldwide, fully paid-up, royalty free, irrevocable limited license (without the right to sublicense) under any applicable copyrights or patent rights it may have in the Specification to create and/or distribute an Independent Implementation of the Specification that: (i) fully implements the Specification without modifying, subsetting or extending the public class or interface declarations whose names begin with "java" or "javax" or their equivalents in any subsequent naming convention adopted by Specification Lead through the Java Community Process, or any recognized successors or replacements thereof; (ii) implement all required interfaces and functionality of the Specification; (iii) only include as part of such Independent Implementation the packages, classes or methods specified by the Specification; (iv) pass the technology compatibility kit (“TCK”) for such Specification; and (v) are designed to operate on a Java platform which is certified to pass the complete TCK for such Java platform. Other than this limited license, you acquire no right, license, title or interest in or to the Specification or any other intellectual property rights of the Specification Lead. You need not include limitations (i)-(iii) from the previous paragraph or any other particular “pass through” requirements in any license You grant concerning the use of your Independent Implementation or products derived from it. However, except with respect to implementations of the Specification (and products derived from them) by your licensee that satisfy limitations (i)-(iii) from the previous paragraph, You may neither: (a) grant or otherwise pass through to your licensees any licenses under Specification Lead’s applicable intellectual property rights; nor (b) authorize your licensees to make any claims concerning their implementation’s compliance with the Spec in question. For the purposes of this Agreement: “Independent Implementation” shall mean an implementation of the Specification that neither derives from the reference implementation to the Specification (“Reference Implementation”) source code or binary code materials nor, except with an appropriate and separate license from licensor of the Reference Implementation, includes any of Reference Implementation’s source code or binary code materials. This Agreement will terminate immediately without notice from Specification Lead if you fail to comply with any material provision of or act outside the scope of the licenses granted above. TRADEMARKS 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 iii 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 Sun or Sun’s licensors, is granted hereunder. Sun, Sun Microsystems, the Sun logo, Java, J2ME, and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. DISCLAIMER OF WARRANTIES THE SPECIFICATION IS PROVIDED “AS IS”. SPECIFICATION LEAD MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT, THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product. THE SPECIFICATION COULD 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. LIMITATION OF LIABILITY TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SPECIFICATION LEAD OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF SPECIFICATION LEAD AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You will indemnify, hold harmless, and defend Specification Lead and its licensors from any claims arising or resulting from: (i) your use of the Specification; (ii) the use or distribution of your Java application, applet and/ or clean room implementation; and/or (iii) any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license. RESTRICTED RIGHTS LEGEND U.S. Government: If this Specification is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government’s rights in the Software and accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions). REPORT You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your use of the Specification (“Feedback”). To the extent that you provide Specification Lead with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Specification Lead a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specification and future versions, implementations, and test suites thereof. iv . 49 LocationListener ................................................................................................ 63 QualifiedCoordinates ...................................................................................................................................................... 33 LandmarkStore ................................ 51 LocationProvider ................... 65 Constant Field Values .............. 35 Location ...................................................................................... 29 LandmarkException .................................................................................................................................................. 79 v .................................................................................................................................................................................................................................................. 43 LocationException .................. 60 ProximityListener .................................................................................................................................................. 5 AddressInfo ..............................................microedition............location ..................................................................................................................... 10 Coordinates . 16 Criteria .............................. 73 Index ........................................................................................................................ 22 Landmark ...................................... 69 Almanac ........................................................................................................................................................................................................................................................................................................................................................................................................................Contents Overview .................................................................................................................................................................................................................................................................................................................................................... 53 Orientation .................................................................................. 1 javax............................................................................................................................................ Contents vi . Limited Device Configuration (CLDC) v1. The minimum platform required by this API is the J2ME Connected. There may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful. it can’t be used with CLDC v1. Micro Edition (J2METM) version 1.0. Preface This specification defines the JSR-179 Location API for J2ME. MAY Indicates that an item is truly optional. MUST NOT The definition is an absolute prohibition of this specification. but the full implications must be understood and carefully weighed before choosing a different course.0. Overview This specification defines a J2ME Optional Package that enables mobile location-based applications for resource limited devices (referred to as ’terminals’ in the following). Mathematical notation for defining ranges of floating point numbers is used as defined below: Where BNF notation is used to define syntax elements. version 1. SHOULD NOT Indicates a non-recommended practice.This API covers obtaining information about the present geographic location and orientation of the terminal and accessing a database of known landmarks stored in the terminal. (Note that due to using the floating point datatypes in this API.) Notation used This specification uses the following terms as they are defined in the table below: Term Definition MUST The associated definition is an absolute requirement of this specification.1 of RFC2616. There may exist valid reasons in particular circumstances to ignore this recommendation. The API is designed to be a compact and generic API that produces information about the present geographic location of the terminal to Java applications.1. SHOULD Indicates a recommended practice.0. the BNF notation is used as defined in section 2.CHA P TER 1 Overview Description This document defines the JSR-179 Location API for the Java 2 Platform. but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label. The API can also be used with the J2ME Connected Device Configuration (CDC). 1 . The Location API for J2ME is designed as an Optional Package that can be used with many J2ME Profiles. In this API. etc. See ’terminal based’ and ’network based’. In this API. The landmarks are usually stored in a local database in the terminal that is represented by the LandmarkStore class in this API. . 2 Network based A location method is network based if the final calculation that gives the location result is performed in the network. Coordinates The geographical coordinates (latitude. In this API. i. Landmark A known geographical location that has a name and a category associated with it. restaurants. Assisted Implies that the other party provides some information assisting determining the location to the party that does the final calculation. longitude. their accuracy.Overview [a. altitude) that identify a location combined with their accuracy information. altitude) that identify a exact location point.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. these are encapsulated in instances of the Coordinates class. direction of the velocity vector. these are encapsulated in instances of the QualifiedCoordinates class. In this API. textual address information for the location (if available) and the timestamp when the location measurement was made.g. the current course and speed of the terminal (if available). Category has an identifying unique name that identifies the category to the end user. These identify a geographical location with some uncertainty of the measurement represented by the accuracy values. often refers to the class Location that encodes the geographical coordinates. often refers to the class Landmark. Terminal based A location method is terminal based if the final calculation that gives the location result is performed in the terminal.b] a closed range from value a to value b with the end-points a and b included in the range (a. Course Course made good. relative to true north.e. For example. museums. Qualified Coordinates The geographical coordinates (latitude. Category Category is used to group Landmarks that are of similar type to the end user.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 Glossary This section defines some terms used in the specification. 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. for a terminal based method ’assisted’ means that the network provides some assistance information.b) an open range from value a to value b with the end-points a and b not included in the range [a. Location Geographical location. e. longitude. It’s definition and Relationships with Local Geodetic Systems. 2002 Report and Contact Comments on this specification are welcome and appreciated. U.Overview References [1] NIMA TR8350. Mobile Location Protocol Specification. Department of Defense [2] NMEA 0183 Interface Standard.0 (MIDP 2.Part 1: Country codes. 2002 [5] ISO 3166-1 Codes for the representation of names of countries and their subdivisions —. v3.S.1).0. 2002 [4] JSR-139 Connected Limited Device Configuration v1.org. v3.1 (CLDC 1.microedition. January 2002 [3] TS 101. International Organization for Standardization [6] JSR-118 Mobile Information Device Profile 2. 3 .0). Comments can be sent to: jsr-179-comments@jcp. Sun Microsystems.loc ation5 The javax.01. National Marine Electronics Association. Motorola and Sun Microsystems. Location Interoperability Forum.0.microedition.location package contains the basic classes needed to request and get a location result.2 World Geodetic System 1984. Package Summary Location Interfaces javax. Overview 4 . Mandatory and optional features This API contains some options whose availability depends on the used location methods. etc. By using the LocationProvider.microedition. the user’s home. this implies that the actual location is within the circle defined by the returned point and radius at a probability of approximately 68%. The implementation may also combine the methods in various ways to get the optimal result. For some location methods. longitude and altitude) and information about their accuracy. The user can store commonly used locations in the database. Examples of landmarks could be e. which has to be taken into account when using the location information in applications. Assuming a normal distribution (which is not necessarily the case). Mandatory features for all location methods are: • Provide latitude and longitude coordinates and their accuracy • Provide timestamp of the location measurement Mandatory other API features for the terminal are: 5 .g.microedition. A landmark is a known physical location that is associated with a name representing that location for the end user. The LocationProvider class represents a module that is able to determine the location of the terminal. e. office.location Description The javax. The landmark database must be shared between all Java applications and may be shared with other applications in the terminal. etc. for example. cellular network based methods. The actual location may thus be also outside of the circle. including native applications. The application can either request a single Location object or be periodically updated with new Location objects via a LocationListener implemented by the application. a timestamp and possibly information about speed and course of the terminal.location package contains the basic classes needed to request and get a location result. but they are unavoidable due to the differences in the underlying location methods. the application can get Location objects representing the location of the terminal at the time of the measurement.g.CHA P TER 2 Package javax. the Location object may also contain an AddressInfo object that includes textual address information. so that the end user has a consistent user experience across all location based applications on the terminal. a street address. This may be implemented using any possible location methods. The 1-sigma confidence refers to the standard deviation of the distribution. These features are not optional in order to allow for differences in the implementations and to cause unnecessary fragmentation. short-range positioning methods like Bluetooth Local Positioning. The location is represented by the Location object that contains a QualifiedCoordinates object representing the geographical coordinates (latitude. satellite based methods like GPS. The Location gives the accuracy of the coordinates as the radius of a circular area indicating the 1-sigma confidence level. Implementations should support all features that are possible with the locations methods that are used. This package also includes a database of landmarks. The application can specify criteria for selecting the location provider and obtain a LocationProvider instance that is able to fulfil these criteria as closely as possible. Those features that are optional to implement have a defined behaviour in the case the feature is not supported by the implementation. Security of this API Some methods in this API are defined to throw a SecurityException if the caller does not have the permissions needed to perform the action. depending on the hardware capabilities of the terminal.ProximityListener LocationProvider.setLocationListener() javax.addProximityListener() javax.location.microedition.Location LocationProvider.location.microedition. LocationProvider. The table below defines the names of the permissions used and the methods that are protected by each permission. every implementation MUST contain all the classes.microedition.javax.getOrientation() javax.Orientation Orientation. interfaces and methods as defined in this specification.LandmarkStore.getInstance().getLocation(). Using the MIDP 2. the security framework of MIDP 2.0 MUST be used as defined below.location • Support one (default) LandmarkStore for storing landmarks Features whose availability depend on the used location method: • Provide altitude information • Provide accuracy of altitude • Provide course and speed information • Provide textual address information related to the location • Provide landmark proximity events Optional features whose availability depend on the landmark store implementation of the terminal and its possible relation to landmark stores shared with native applications: • Creating and deleting landmark stores • Adding and removing landmark categories Additionally. This MUST be enforced by an appropriate security framework in the platform.microedition. The definition of the policy for these permissions is out of scope for this specification.microedition. LandmarkStore.read LandmarkStore.listLandmarkStores() 6 . Permission name Methods protected by this permission javax. the following features are optionally supported: • Provide the compass azimuth of the terminal orientation • Provide the pitch and roll 3D terminal orientation information In general.0 Security Framework If this API is implemented on the MIDP 2.0 platform.location.location. LandmarkStore. leave other parameters // at default values. LandmarkStore. because the getLocation method may block for a long time.deleteLandmarkStore() Identification of the Location API To enable applications to test for the presence of the Location API and its version during runtime.getLocation(60). LandmarkStore.LandmarkStore.updateLandmark() javax.. Platforms where this API is implemented according to this specification shall include a system property with a key “microedition.LandmarkStore.catego ry LandmarkStore.addCategory(). } The following example illustrates how to use the LocationListener for subscribing to periodic location updates. LandmarkStore.manage ment LandmarkStore.location. // Specify horizontal accuracy of 500 meters.deleteCategory() javax.. This piece of code illustrates obtaining the location syncronously.LandmarkStore.getQualifiedCoordinates().microedition.location. // get the location.location.javax.version”. When System.createLandmarkStore().microedition. try { // Create a Criteria object for defining desired selection criteria Criteria cr = new Criteria().. An application would normally perform this within a separate thread. implementations conforming to this specification shall return the version string “1. if (c != null) { // use coordinate information . 7 .0”. Coordinates c = l.removeLandmarkFromCategory().setHorizontalAccuracy(500).write LandmarkStore. This example creates a handler thread to handle the updates so that the methods on the listener would not block the platform implementation threads for a long time.location.getProperty is called with this key..microedition.addLandmark().location javax. LandmarkStore. a system property is defined. cr. one minute timeout Location l = lp. LocationProvider lp = LocationProvider. Example of Usage The following piece of code illustrates how to obtain the current location of the terminal.getInstance(cr).microedition.deleteLandmark(). } } catch (LocationException e) { // not able to retrive location information . start().getQualifiedCoordinates(). LocationProvider provider. provider. new Thread(handler). } private void processUpdate(Location update) { if ( update. } public void locationUpdated(LocationProvider provider. public MovementTracker(float movementDistance) throws LocationException { this.setLocationListener(this. boolean done.location class MovementTracker implements LocationListener { float movementDistance.getInstance(null). Location location) { handler.getQualifiedCoordinates() ) > movementDistance ) { // Alert user to movement.movementDistance = movementDistance. Location lastValidLocation. int newState) { } class UpdateHandler implements Runnable { private Location updatedLocation = null.handleUpdate(location). -1).. } // // // // if The benefit of the MessageListener is here. This thread could via similar triggers be handling other kind of events as well in addition to just receiving the location updates.javax. UpdateHandler handler. (locationToBeHandled != null) processUpdate(locationToBeHandled). } public void providerStateChanged(LocationProvider provider. notify(). updatedLocation = null.microedition. } } public synchronized void handleUpdate(Location update) { updatedLocation = update. done = false.distance( lastValidLocation. // The run method performs the actual processing of the location // updates public void run() { Location locationToBeHandled = null. -1. } 8 . provider = LocationProvider. while (!done) { synchronized(this) { if (updatedLocation == null) { try { wait(). handler = new UpdateHandler(). } catch (Exception e) { // Handle interruption } } locationToBeHandled = updatedLocation. -1. // Cache new position as we have moved a sufficient distance // from last one lastValidLocation = location.. microedition. Location43 The Location class represents the standard set of basic location information. LocationProvider53 This is the starting point for applications using this API and represents a source of the location information. Orientation60 The Orientation class represents the physical orientation of the terminal.location } } } Since: LAPI 1. QualifiedCoordinates65 The QualifiedCoordinates class represents coordinates as latitude-longitudealtitude values that are associated with an accuracy value. Exceptions LandmarkException33 The LandmarkException is thrown when an error related to handling landmarks has occurred. Classes AddressInfo10 The AddressInfo class holds textual address information about a location.javax. Criteria22 The criteria used for the selection of the location provider is defined by the values in this class. LandmarkStore35 The LandmarkStore class provides methods to store. LocationException49 The LocationException is thrown when a location API specific error has occurred. Coordinates16 The Coordinates class represents coordinates as latitude-longitude-altitude values. i.0 Class Summary Interfaces LocationListener51 The LocationListener represents a listener that receives events associated with a particular LocationProvider. Landmark29 The Landmark class represents a landmark.e. 9 . ProximityListener63 This interface represents a listener to events associated with detecting proximity to some registered coordinates. delete and retrieve landmarks from a persistent landmark store. postal code. Typically the information is e. This class is only a container for the information. Below are some typical examples of addresses in different countries and how they map to the AddressInfo fields. it is set to null. Addresses for other countries should map these to the closest corresponding entities used in that country. street. The getField method returns the value set for the defined field using the setField method. Defined field constants can be used to retrieve field data. street address.AddressInfo javax. When the platform implementation returns AddressInfo objects. The information is divided into fields (e. etc.location javax.microedition.g.AddressInfo Description The AddressInfo class holds textual address information about a location.location AddressInfo Declaration public class AddressInfo Object | +--javax.). it MUST ensure that it only returns objects where the parameters have values set as described for their semantics in this class. city.g. If the value of a field is not available.microedition.location. The names of the fields use terms and definitions that are commonly used e.microedition. AddressInfo Field American Example British Example EXTENSION Flat 5 The Oaks STREET 10 Washington Street 20 Greenford Court POSTAL_CODE 12345 AB1 9YZ CITY Palo Alto Cambridge COUNTY Santa Clara County Cambridgeshire STATE California England COUNTRY United States of America United Kingdom COUNTRY_CODE US GB DISTRICT BUILDING_NAME BUILDING_FLOOR BUILDING_ROOM BUILDING_ZONE CROSSING1 CROSSING2 10 . in the United States.g. notifyAll().location URL http://www.americanurl.String getField(int field)14 void setField(int field.com AddressInfo BUILDING_FLOOR http://britishurl. toString().co.microedition. String value)14 Inherited Member Summary Methods inherited from class Object equals(Object).lang. notify(). 11 . hashCode(). wait().uk PHONE_NUMBER Member Summary Fields static static static static static static static static static static static static static static static static static int int int int int int int int int int int int int int int int int BUILDING_FLOOR11 BUILDING_NAME12 BUILDING_ROOM12 BUILDING_ZONE12 CITY12 COUNTRY12 COUNTRY_CODE12 COUNTY12 CROSSING113 CROSSING213 DISTRICT13 EXTENSION13 PHONE_NUMBER13 POSTAL_CODE13 STATE13 STREET14 URL14 Constructors AddressInfo()14 Methods java. wait() Fields BUILDING_FLOOR Declaration: public static final int BUILDING_FLOOR Description: Address field denoting a building floor.javax. getClass(). wait(). BUILDING_ROOM Declaration: public static final int BUILDING_ROOM Description: Address field denoting a building room. which is an entity between a state and a city 12 . BUILDING_ZONE Declaration: public static final int BUILDING_ZONE Description: Address field denoting a building zone CITY Declaration: public static final int CITY Description: Address field denoting town or city name.AddressInfo BUILDING_NAME javax.location BUILDING_NAME Declaration: public static final int BUILDING_NAME Description: Address field denoting a building name.microedition. COUNTRY_CODE Declaration: public static final int COUNTRY_CODE Description: Address field denoting country as a two-letter ISO 3166-1 code. COUNTRY Declaration: public static final int COUNTRY Description: Address field denoting country. COUNTY Declaration: public static final int COUNTY Description: Address field denoting a county. microedition.g. 13 . EXTENSION Declaration: public static final int EXTENSION Description: Address field denoting address extension. POSTAL_CODE Declaration: public static final int POSTAL_CODE Description: Address field denoting zip or postal code. flat number. e. CROSSING2 Declaration: public static final int CROSSING2 Description: Address field denoting a street in a crossing. STATE Declaration: public static final int STATE Description: Address field denoting state or province. PHONE_NUMBER Declaration: public static final int PHONE_NUMBER Description: Address field denoting a phone number for this place.javax.location AddressInfo CROSSING1 CROSSING1 Declaration: public static final int CROSSING1 Description: Address field denoting a street in a crossing. DISTRICT Declaration: public static final int DISTRICT Description: Address field denoting a municipal district. microedition. If the field is not available null is returned. Constructors AddressInfo() Declaration: public AddressInfo() Description: Constructs an AddressInfo object with all the values of the fields set to null. If the field is not set. New York.the ID of the field to be retrieved Returns: the address field string. returns null. Example: getField(AddressInfo. URL Declaration: public static final int URL Description: Address field denoting a URL for this place. String) Declaration: public void setField(int field. String)14 setField(int. String value) 14 . Methods getField(int) Declaration: public String getField(int field) Description: Returns the value of an address field. Parameters: field . Throws: IllegalArgumentException . or null if not available.location STREET Declaration: public static final int STREET Description: Address field denoting street name and number.if the parameter field ID is not one of the constant values defined in this class See Also: setField(int.AddressInfo STREET javax.STREET) might return “113 Broadway” if the location is on Broadway. Parameters: field .microedition.the new value for the field. Throws: IllegalArgumentException .location AddressInfo setField(int.if the parameter field ID is not one of the constant values defined in this class See Also: getField(int)14 15 . null is used to indicate that the field has no content.javax.the ID of the field to be set value . String) Description: Sets the value of an address field. The degrees are in decimal values (rather than minutes/seconds). The coordinates are given using the WGS84 datum.Coordinates javax. double longitude. Member Summary Fields static int DD_MM17 static int DD_MM_SS17 Constructors Coordinates(double latitude.microedition. This class also provides convenience methods for converting between a string coordinate representation and the double representation used in this class. The latitude and longitude values are expressed in degrees using floating point values.Coordinates Direct Known Subclasses: QualifiedCoordinates65 Description The Coordinates class represents coordinates as latitude-longitude-altitude values.String static double float float double double void void void azimuthTo(Coordinates to)18 convert(double coordinate. int outputType)18 convert(String coordinate)18 distance(Coordinates to)19 getAltitude()20 getLatitude()20 getLongitude()20 setAltitude(float altitude)20 setLatitude(double latitude)21 setLongitude(double longitude)21 Inherited Member Summary Methods inherited from class Object 16 .microedition.microedition.location javax.lang.location Coordinates Declaration public class Coordinates Object | +--javax. float altitude)17 Methods float static java.location. wait(). longitude . The Float.location Coordinates DD_MM Inherited Member Summary equals(Object).the latitude of the location. altitude . Valid range: [-180.NaN can be used to indicate that altitude is not known. double. hashCode().if an input parameter is out of the valid range 17 . double longitude. float) Declaration: public Coordinates(double latitude. The degrees are in decimal values (rather than minutes/ seconds).the longitude of the location. decimal fractions of a minute DD_MM_SS Declaration: public static final int DD_MM_SS Description: Identifier for string coordinate representation Degrees. notify(). float altitude) Description: Constructs a new Coordinates object with the values specified. getClass(). defined as height above the WGS84 ellipsoid. Minutes. 90.javax. Positive values indicate northern latitude and negative values southern latitude.the altitude of the location in meters. Positive values indicate eastern longitude and negative values western longitude. toString(). Parameters: latitude . wait() Fields DD_MM Declaration: public static final int DD_MM Description: Identifier for string coordinate representation Degrees. Float. 180.0).0.0]. The coordinate values always apply to the WGS84 datum. Minutes. wait(). Throws: IllegalArgumentException .microedition.0.NaN value can be used for altitude to indicate that altitude is not known. The latitude and longitude parameters are expressed in degrees using floating point values. Valid range: [-90. Seconds and decimal fractions of a second Constructors Coordinates(double. notifyAll(). a double reprentation of a coordinate outputType .the Coordinates of the destination Returns: the azimuth to the destination in degrees.0.location Methods azimuthTo(Coordinates) Declaration: public float azimuthTo(javax.location.identifier of the type of the string representation wanted for output The constant DD_MM_SS identifies the syntax 1 and the constant DD_MM identifies the syntax 2. The implementation shall provide as many significant digits for the decimal fractions as are allowed by the string syntax definition.microedition. this method returns 180.0).0. The Coordinates object on which this method is called is considered the origin for the calculation and the Coordinates object passed as a parameter is the destination which the azimuth is calculated to. Parameters: coordinate . it is required that the result is within 1 degree of the correct result. When the origin is the North pole and the destination is not the North pole. If the origin is equal to the destination. When the origin is the South pole and the destination is not the South pole.NaN See Also: convert(String)18 convert(String) Declaration: public static double convert(String coordinate) Description: Converts a String representation of a coordinate into the double representation as used in this API.Coordinates16 to) Description: Calculates the azimuth between the two points according to the ellipsoid model of WGS84. this method returns 0.if the parameter is null convert(double.if the outputType is not one of the two costant values defined in this class or if the coordinate value is not within the range [-180. Parameters: to . However.Coordinates azimuthTo(Coordinates) javax.0 . There are string syntaxes supported are the same as for the convert(String) method.0. Returns: a string representation of the coordinate in a representation indicated by the parameter Throws: IllegalArgumentException . int) Declaration: public static String convert(double coordinate. The implementation shall calculate the result as exactly as it can. 180. There are two string syntaxes supported: 18 .microedition.0) or is Double. this method returns 0. int outputType) Description: Converts a double representation of a coordinate with decimal degrees into a string representation. Throws: NullPointerException .360. The azimuth is relative to true north. Result is within the range [0.0. seconds and decimal fractions of seconds. Parameters: coordinate . This is expressed as a string complying with the following BNF definition where the degrees are within the range [-179.6”.” decimalfrac | degrees “:” minutes degrees = degreedigits | “-” degreedigits degreedigits = digit | nonzerodigit digit | “1” digit digit minutes = minsecfirstdigit digit decimalfrac = 1*5digit digit = “0” | “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9” nonzerodigit = “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9” minsecfirstdigit = “0” | “1” | “2” | “3” | “4” | “5” For example. it is required that the result is within 0.if the coordinate input parameter does not comply with the defined syntax for the specified types NullPointerException . The implementation shall calculate this as exactly as it can.Coordinates16 to) Description: Calculates the geodetic distance between the two points according to the ellipsoid model of WGS84. 59]. or the degrees is -180 and the minutes. the corresponding syntax 1 string is “61:30:36” and the corresponding syntax 2 string is “61:30.the Coordinates of the destination 19 .a String in either of the two representation specified above Returns: a double value with decimal degrees that matches the string representation given as the parameter Throws: IllegalArgumentException . This is expressed as a string complying with the following BNF definition where the degrees are within the range [-179. for the double value of the coordinate 61.51d.location Coordinates distance(Coordinates) 1. 179] and the minutes are within the range [0. 179] and the minutes and seconds are within the range [0. seconds and decimal fractions are 0: coordinate = degrees “:” minutes “:” seconds “.35% of the correct result. However. Degrees.if the coordinate string is null distance(Coordinates) Declaration: public float distance(javax. Parameters: to . 59]. Degrees.microedition. Altitude is neglected from calculations.microedition.” decimalfrac | degrees “:” minutes “:” seconds | degrees “:” minutes degrees = degreedigits | “-” degreedigits degreedigits = digit | nonzerodigit digit | “1” digit digit minutes = minsecfirstdigit digit seconds = minsecfirstdigit digit decimalfrac = 1*3digit digit = “0” | “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9” nonzerodigit = “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9” minsecfirstdigit = “0” | “1” | “2” | “3” | “4” | “5” 2. or the degrees is -180 and the minutes and decimal fractions are 0: coordinate = degrees “:” minutes “. minutes and decimal fractions of minutes.javax.location. minutes. Positive values indicate eastern longitude and negative values western longitude.0 means a location at the ellipsoid surface. negative values mean the location is below the ellipsoid surface. Float.NaN that the altitude is not available. Positive values indicate northern latitude and negative values southern latitude. Returns: the latitude in degrees See Also: setLatitude(double)21 getLongitude() Declaration: public double getLongitude() Description: Returns the longitude component of this coordinate. 0. Parameters: altitude .location Returns: the distance to the destination in meters Throws: NullPointerException . The longitude is given in WGS84 datum.the altitude of the location in meters. The latitude is given in WGS84 datum. Altitude is defined to mean height above the WGS84 reference ellipsoid. Float. defined as height above the WGS84 ellipsoid.NaN that the altitude is not available 20 . negative values mean the location is below the ellipsoid surface.0 means a location at the ellipsoid surface.Coordinates getAltitude() javax.microedition.if the parameter is null getAltitude() Declaration: public float getAltitude() Description: Returns the altitude component of this coordinate. Returns: the altitude in meters above the reference ellipsoid See Also: setAltitude(float)20 getLatitude() Declaration: public double getLatitude() Description: Returns the latitude component of this coordinate. Returns: the longitude in degrees See Also: setLongitude(double)21 setAltitude(float) Declaration: public void setAltitude(float altitude) Description: Sets the geodetic altitude for this point. 0. 0. Longitude is given as a double expressing the longitude in degrees in the WGS84 datum.if latitude is out of the valid range See Also: getLatitude()20 setLongitude(double) Declaration: public void setLongitude(double longitude) Description: Sets the geodetic longitude for this point. Parameters: longitude . Latitude is given as a double expressing the latitude in degrees in the WGS84 datum.0. Valid range: [-180.location Coordinates setLatitude(double) See Also: getAltitude()20 setLatitude(double) Declaration: public void setLatitude(double latitude) Description: Sets the geodetic latitude for this point. 180.if longitude is out of the valid range See Also: getLongitude()20 21 . Parameters: latitude .javax.0) Throws: IllegalArgumentException . Throws: IllegalArgumentException .the longitude of the location in degrees.0].the latitude component of this location in degrees.microedition. 90. Valid range: [-90. the cost criteria field is treated differently from others. where the judgement of sufficiently close is an implementation dependent best effort choice. The different criteria fields do not have any defined priority order but the implementation uses some implementation specific logic to choose the location provider that can typically best meet the defined criteria. an implementation is not required to return a location provider if it does not have any available provider that is able to meet these criteria or be sufficiently close to meeting them.location javax.microedition. It is left up to the implementation to consider what is close enough to the specified requirements that it is worth providing the location provider to the application.microedition.location. The default values are always the least restrictive option that will match all location providers. However.location Criteria Declaration public class Criteria Object | +--javax. The default values for the criteria fields are specified below in the table.getInstance method call. The implementation considers the different criteria fields to choose the location provider that best fits the defined criteria.Criteria javax. If there is no available location provider that is able to meet all the specified criteria.microedition. It is up to the implementation to provide a LocationProvider that can obtain locations constrained by these values. Instances of Criteria are used by the application to indicate criteria for choosing the location provider in the LocationProvider. However. the implementation is allowed to make its own best effort selection of a location provider that is closest to the defined criteria (provided that the cost criteria is met). If the application has set the cost field to indicate that the returned location provider is not allowed to incur financial cost to the end user.Criteria Description The criteria used for the selection of the location provider is defined by the values in this class. Default values: Criteria field Default value Horizontal accuracy NO_REQUIREMENT Vertical accuracy NO_REQUIREMENT Preferred response time NO_REQUIREMENT Power consumption NO_REQUIREMENT Cost allowed true (allowed to cost) Speed and course required false (not required) 22 Altitude required false (not required) Address info required false (not required) . the implementation MUST guarantee that the returned location provider does not incur cost. 23 . but the consequence may be that no matching LocationProvider can be created.location Criteria NO_REQUIREMENT The implementation of this class only retains the values that are passed in using the set* methods.microedition. wait() Fields NO_REQUIREMENT Declaration: public static final int NO_REQUIREMENT Description: Constant indicating no requirements for the parameter. notifyAll(). notify(). even negative values. wait(). Applications may set any values it likes. Member Summary Fields static static static static int int int int NO_REQUIREMENT23 POWER_USAGE_HIGH24 POWER_USAGE_LOW24 POWER_USAGE_MEDIUM24 Constructors Criteria()24 Methods int int int int boolean boolean boolean boolean void void void void void void void void getHorizontalAccuracy()24 getPreferredPowerConsumption()24 getPreferredResponseTime()25 getVerticalAccuracy()25 isAddressInfoRequired()25 isAllowedToCost()25 isAltitudeRequired()25 isSpeedAndCourseRequired()26 setAddressInfoRequired(boolean addressInfoRequired)26 setAltitudeRequired(boolean altitudeRequired)26 setCostAllowed(boolean costAllowed)26 setHorizontalAccuracy(int accuracy)27 setPreferredPowerConsumption(int level)27 setPreferredResponseTime(int time)27 setSpeedAndCourseRequired(boolean speedAndCourseRequired)28 setVerticalAccuracy(int accuracy)28 Inherited Member Summary Methods inherited from class Object equals(Object). It does not try to validate the values of the parameters in any way.javax. toString(). wait(). hashCode(). getClass(). All the fields are set to the default values that are specified below in the specification of the set* methods for the parameters.location POWER_USAGE_HIGH Declaration: public static final int POWER_USAGE_HIGH Description: Level indicating high power consumption allowed.microedition.Criteria POWER_USAGE_HIGH javax. Constructors Criteria() Declaration: public Criteria() Description: Constructs a Criteria object. Methods getHorizontalAccuracy() Declaration: public int getHorizontalAccuracy() Description: Returns the horizontal accuracy value set in this Criteria. POWER_USAGE_LOW Declaration: public static final int POWER_USAGE_LOW Description: Level indicating only low power consumption allowed. POWER_USAGE_MEDIUM Declaration: public static final int POWER_USAGE_MEDIUM Description: Level indicating average power consumption allowed. Returns: the horizontal accuracy in meters See Also: setHorizontalAccuracy(int)27 getPreferredPowerConsumption() Declaration: public int getPreferredPowerConsumption() 24 . true means that it should be able.microedition. See Also: setCostAllowed(boolean)26 isAltitudeRequired() Declaration: public boolean isAltitudeRequired() 25 . POWER_USAGE_MEDIUM. See Also: setAddressInfoRequired(boolean)26 isAllowedToCost() Declaration: public boolean isAllowedToCost() Description: Returns the preferred cost setting. should be one of NO_REQUIREMENT. POWER_USAGE_HIGH. true if allowed to cost. Returns: the preferred cost setting. Returns: whether the location provider should be able to normally provide textual address information. Returns: the power consumption level.location Criteria getPreferredResponseTime() Description: Returns the preferred power consumption. Returns: the maximum response time in milliseconds See Also: setPreferredResponseTime(int)27 getVerticalAccuracy() Declaration: public int getVerticalAccuracy() Description: Returns the vertical accuracy value set in this Criteria. Returns: the accuracy in meters See Also: setVerticalAccuracy(int)28 isAddressInfoRequired() Declaration: public boolean isAddressInfoRequired() Description: Returns whether the location provider should be able to determine textual address information. POWER_USAGE_LOW. false if it must be free of charge. See Also: setPreferredPowerConsumption(int)27 getPreferredResponseTime() Declaration: public int getPreferredResponseTime() Description: Returns the preferred maximum response time.javax. false means that this is not required. Parameters: altitudeRequired . false means that this is not required. Parameters: addressInfoRequired .Criteria isSpeedAndCourseRequired() javax. if set the false. Returns: whether the location provider should be able to determine altitude. Default is false. See Also: setSpeedAndCourseRequired(boolean)28 setAddressInfoRequired(boolean) Declaration: public void setAddressInfoRequired(boolean addressInfoRequired) Description: Sets whether the location provider should be able to determine textual address information. See Also: isAltitudeRequired()25 setCostAllowed(boolean) Declaration: public void setCostAllowed(boolean costAllowed) 26 . See Also: isAddressInfoRequired()25 setAltitudeRequired(boolean) Declaration: public void setAltitudeRequired(boolean altitudeRequired) Description: Sets whether the location provider should be able to determine altitude. See Also: setAltitudeRequired(boolean)26 isSpeedAndCourseRequired() Declaration: public boolean isSpeedAndCourseRequired() Description: Returns whether the location provider should be able to determine speed and course. true means that it should be able. the LocationProvider is required to be able to normally determine the altitude if set the false. This does not mean that every returned location instance necessarily will have all the address information filled in. the altitude is not required. the LocationProvider is required to be able to normally determine the textual address information. Returns: whether the location provider should be able to determine speed and course.microedition. the textual address information is not required. Setting this criteria to true implies that a location provider should be selected that is capable of providing the textual address information. Default is false. though. true means that it should be able.location Description: Returns whether the location provider should be able to determine altitude. false means that this is not required.if set to true.if set to true. true if it is allowed to cost See Also: isAllowedToCost()25 setHorizontalAccuracy(int) Declaration: public void setHorizontalAccuracy(int accuracy) Description: Sets the desired horizontal accuracy preference.location Criteria setHorizontalAccuracy(int) Description: Sets the preferred cost setting. Parameters: costAllowed . Parameters: accuracy . Default is NO_REQUIREMENT. the method is allowed to cost.microedition. Accuracy is measured in meters. These levels are inherently indeterminable and depend on many factors. The preference indicates maximum allowed typical 1-sigma standard deviation for the location method.the preferred maximum level of power consumption. When this criteria is set to false. POWER_USAGE_MEDIUM.e.javax. i. See Also: getPreferredPowerConsumption()24 setPreferredResponseTime(int) Declaration: public void setPreferredResponseTime(int time) 27 . Sets whether the requests for location determination is allowed to incur any financial cost to the user of the terminal. meaning power consumption is not a quality parameter. Default is NO_REQUIREMENT.false if location determination is not allowed to cost. meaning no preference on horizontal accuracy. the implementation may only return a LocationProvider of which it is certain that using it for determining the location does not cause a per usage cost to the end user. If the implementation doesn’t know. Note that the platform implementation may not always be able to know if a location method implies cost to the end user or not. Should be one of NO_REQUIREMENT. POWER_USAGE_HIGH.the preferred horizontal accuracy in meters See Also: getHorizontalAccuracy()24 setPreferredPowerConsumption(int) Declaration: public void setPreferredPowerConsumption(int level) Description: Sets the preferred maximum level of power consumption. It is the judgement of the implementation that defines a positioning method as consuming low power or high power. The default is true. Parameters: level . it MUST assume that it may cost. POWER_USAGE_LOW. Default is false. Default is NO_REQUIREMENT. Accuracy is measured in meters. the LocationProvider is required to be able to normally determine the speed and course. Parameters: accuracy . the speed and course are not required.the preferred time constraint and timeout value in milliseconds See Also: getPreferredResponseTime()25 setSpeedAndCourseRequired(boolean) Declaration: public void setSpeedAndCourseRequired(boolean speedAndCourseRequired) Description: Sets whether the location provider should be able to determine speed and course.location Description: Sets the desired maximum response time preference. See Also: isSpeedAndCourseRequired()26 setVerticalAccuracy(int) Declaration: public void setVerticalAccuracy(int accuracy) Description: Sets the desired vertical accuracy preference. Parameters: speedAndCourseRequired . meaning no response time constraint.Criteria setSpeedAndCourseRequired(boolean) javax.if set to true.the preferred vertical accuracy in meters See Also: getVerticalAccuracy()25 28 . Parameters: time . This value is typically used by the implementation to determine a location method that typically is able to produce the location information within the defined time. meaning no preference on vertical accuracy. if set the false.microedition. Default is NO_REQUIREMENT. The preference indicates maximum allowed typical 1-sigma standard deviation for the location method. notifyAll(). When the platform implementation returns Landmark objects. wait().lang. wait(). toString(). it MUST ensure that it only returns objects where the parameters have values set as described for their semantics in this class. The get* methods return the values passed in the constructor.location Landmark javax.e. a textual description.microedition. String description. getClass().location. a known location with a name. A landmark has a name by which it is known to the end user.javax. This class is only a container for the information. wait() 29 .String java. hashCode().Landmark Description The Landmark class represents a landmark. Member Summary Constructors Landmark(String name.lang.microedition. except the name field is never allowed to be null.microedition. QualifiedCoordinates and optionally AddressInfo.String QualifiedCoordinates void void void void getAddressInfo()30 getDescription()30 getName()30 getQualifiedCoordinates()31 setAddressInfo(AddressInfo addressInfo)31 setDescription(String description)31 setName(String name)31 setQualifiedCoordinates(QualifiedCoordinates coordinates)32 Inherited Member Summary Methods inherited from class Object equals(Object). notify(). QualifiedCoordinates coordinates. i. The constructor does not validate the parameters passed in but just stores the values. AddressInfo addressInfo)30 Methods AddressInfo java.location Landmark Declaration public class Landmark Object | +--javax. 30 .the Coordinates of the landmark. May be null if not known. javax.location. javax. May be null if not available. String.microedition.AddressInfo10 addressInfo) Description: Constructs a new Landmark object with the values specified. String description.the textual address information of the landmark. AddressInfo) Constructors Landmark(String.the name of the landmark description .microedition. coordinates .location Landmark(String.description of the landmark.microedition. Throws: NullPointerException .AddressInfo10 getAddressInfo() Description: Gets the AddressInfo of the landmark.if the name is null Methods getAddressInfo() Declaration: public javax.location. May be null if not known. String. null if not available See Also: setDescription(String)31 getName() Declaration: public String getName() Description: Gets the landmark name.QualifiedCoordinates65 coordinates. QualifiedCoordinates.location.Landmark javax. Returns: the AddressInfo of the landmark See Also: setAddressInfo(AddressInfo)31 getDescription() Declaration: public String getDescription() Description: Gets the landmark description. Returns: returns the description of the landmark. AddressInfo) Declaration: public Landmark(String name.microedition. Parameters: name . addressInfo . QualifiedCoordinates. javax.microedition.location Landmark getQualifiedCoordinates() Returns: the name of the landmark See Also: setName(String)31 getQualifiedCoordinates() Declaration: public javax.microedition.location.QualifiedCoordinates65 getQualifiedCoordinates() Description: Gets the QualifiedCoordinates of the landmark. Returns: the QualifiedCoordinates of the landmark. null if not available. See Also: setQualifiedCoordinates(QualifiedCoordinates)32 setAddressInfo(AddressInfo) Declaration: public void setAddressInfo(javax.microedition.location.AddressInfo10 addressInfo) Description: Sets the AddressInfo of the landmark. Parameters: addressInfo - the AddressInfo of the landmark See Also: getAddressInfo()30 setDescription(String) Declaration: public void setDescription(String description) Description: Sets the description of the landmark. Parameters: description - description for the landmark, null may be passed in to indicate that description is not available. See Also: getDescription()30 setName(String) Declaration: public void setName(String name) Description: Sets the name of the landmark. Parameters: name - name for the landmark Throws: NullPointerException - if the parameter is null See Also: getName()30 31 Landmark javax.microedition.location setQualifiedCoordinates(QualifiedCoordinates) setQualifiedCoordinates(QualifiedCoordinates) Declaration: public void setQualifiedCoordinates(javax.microedition.location.QualifiedCoordinates65 coordinates) Description: Sets the QualifiedCoordinates of the landmark. Parameters: coordinates - the qualified coordinates of the landmark See Also: getQualifiedCoordinates()31 32 javax.microedition.location LandmarkException javax.microedition.location LandmarkException Declaration public class LandmarkException extends Exception Object | +--Throwable | +--Exception | +--javax.microedition.location.LandmarkException Description The LandmarkException is thrown when an error related to handling landmarks has occurred. Member Summary Constructors LandmarkException()33 LandmarkException(String s)33 Inherited Member Summary Methods inherited from class Object equals(Object), getClass(), hashCode(), notify(), notifyAll(), wait(), wait(), wait() Methods inherited from class Throwable getMessage(), printStackTrace(), toString() Constructors LandmarkException() Declaration: public LandmarkException() Description: Constructs a LandmarkException with no detail message. LandmarkException(String) Declaration: public LandmarkException(String s) 33 LandmarkException LandmarkException(String) javax.microedition.location Description: Constructs a LandmarkException with the specified detail message. Parameters: s - the detailed message 34 Named landmark stores have unique names in this API.) for the MIDP 2. All landmark stores MUST be shared between all J2ME applications and MAY be shared with native applications in the terminal. The category is intended to group landmarks that are of similar type to the end user.microedition.location. However.javax. A Landmark object is initially constructed by an application when it has been constructed using the constructor but has not been added to a LandmarkStore using addLandmark. Landmarks with the same name can appear in multiple categories or even several Landmarks with the same name in the same category. The implementation may support creating and deleting landmark stores by the application. The permissions (names etc. e.g. If the underlying implementation allows multiple landmark stores with the same name.location LandmarkStore Declaration public class LandmarkStore Object | +--javax. 35 .microedition. it must present them with unique names in the API e. even if the landmark information in the store is modified subsequently by this or some other application.g. if the calling application does not have the required permissions. An application having e. Accessing the landmark store may cause a SecurityException. The Landmark object instances can be in two states: • initially constructed by an application • belongs to a LandmarkStore A Landmark object belongs to a LandmarkStore if it has been obtained from the LandmarkStore using getLandmarks or if it has been added to the LandmarkStore using addLandmark. The Landmark objects returned from the getLandmarks methods in this class shall guarantee that the application can read a consistent set of the landmark data valid at the time of obtaining the object instance.LandmarkStore Description The LandmarkStore class provides methods to store. The category names describe the category to the end user. The names of the categories are unique within a LandmarkStore. The language used in the names may be any and depends on the preferences of the end user.microedition. a permission to read landmarks wouldn’t necessarily have the permission to delete them. The landmark names are strings that identify the landmark to the end user.0 security framework are defined elsewhere in this specification. etc. The landmark stores created by an application and landmarks added in landmark stores persist even if the application itself is deleted from the terminal. The Landmarks have a name and may be placed in a category or several categories. The permissions to read and write (including add and delete) landmarks are distinct.location LandmarkStore javax. There is one default landmark store and there may be multiple other named landmark stores. delete and retrieve landmarks from a persistent landmark store. the names of the landmarks are not guaranteed to be unique.g. museums. restaurants. by adding some postfix to those names that have multiple instances in order to differentiate them. hashCode(). wait() Methods addCategory(String) Declaration: public void addCategory(String categoryName) throws LandmarkException.util. String category)41 void updateLandmark(Landmark lm)42 Inherited Member Summary Methods inherited from class Object equals(Object).Enumeration java. All implementations must support names that have length up to and including 32 characters.if the parameter is null LandmarkException33 . wait(). double minLongitude.microedition. wait().io.if a category with the specified name already exists NullPointerException .IOException .Enumeration getLandmarks(String category. double maxLongitude)40 java. String name)41 static listLandmarkStores()41 java.util.util.Enumeration static LandmarkStore java. notify().Enumeration addCategory(String categoryName)36 addLandmark(Landmark landmark. notifyAll().lang.LandmarkStore addCategory(String) javax.if the application does not have the permission to manage categories 36 . String category)37 createLandmarkStore(String storeName)37 deleteCategory(String categoryName)38 deleteLandmark(Landmark lm)38 deleteLandmarkStore(String storeName)39 getCategories()39 getInstance(String storeName)39 getLandmarks()40 getLandmarks(String category. IOException Description: Adds a category to this LandmarkStore.String[] void removeLandmarkFromCategory(Landmark lm. If the provided name is longer it may be truncated by the implementation if necessary.name for the category to be added Throws: IllegalArgumentException .location Member Summary Methods void void static void void void static void java. toString().if this LandmarkStore does not support adding new categories java. double minLatitude. double maxLatitude. getClass().if an I/O error occurs or there are no resources to add a new category SecurityException . Parameters: categoryName .util. String category) throws IOException Description: Adds a landmark to the specified group in the landmark store.microedition.IOException . If the Landmark object that is passed as a parameter is an instance initially constructed by the application using the constructor or an instance that belongs to a different LandmarkStore. If an application tries to add a Landmark with a longer name field than the implementation can support.if an I/O error happened when accessing the landmark store or if there are no resources available to store this landmark NullPointerException . If the Landmark object that is passed as a parameter is an instance that belongs to this LandmarkStore. null can be used to indicate that the landmark does not belong to a category Throws: SecurityException . However.if the landmark has a longer name field than the implementation can support or if the category is not null or one of the categories defined in this LandmarkStore java. every implementation is required to be able to store a landmark where each String field is set to a 30 character long string. LandmarkException Description: Creates a new landmark store with a specified name. the implementation is allowed to automatically truncate fields that are too long. it will be added back when this method is called. If some textual String field inside the landmark object is set to a value that is too long to be stored. However.microedition. IllegalArgumentException is thrown. Parameters: landmark .javax. Every implementation shall be able to support name fields that are 32 characters or shorter.category where the landmark is added. Implementations may support longer names but are not required to.if the application is not allowed to add landmarks IllegalArgumentException . If the landmark already belongs to the specified category. String) addLandmark(Landmark. a new landmark will be created in this LandmarkStore and it will belong initially to only the category specified in the category parameter. After this method call.location LandmarkStore addLandmark(Landmark. All LandmarkStores are shared between all J2ME applications and may be shared with native applications.the landmark to be added category . the 37 .Landmark29 landmark. the same landmark instance will be added to the specified category in addition to the category/categories which it already belongs to.io. the Landmark object that is passed as a parameter belongs to this LandmarkStore.if the landmark parameter is null createLandmarkStore(String) Declaration: public static void createLandmarkStore(String storeName) throws IOException. the name field MUST NOT be truncated. this method returns with no effect. When the landmark store is empty. Implementations may support creating landmark stores on a removable media. String) Declaration: public void addLandmark(javax.location. If the landmark has been deleted after obtaining it from getLandmarks. name for the category to be removed Throws: NullPointerException . only the associated category information from the landmarks. this method will not remove any of the landmarks. prompt the end user to make the choice if the implementation supports several storage media.if this LandmarkStore does not support deleting categories java.io. The implementation of this method may e.LandmarkStore deleteCategory(String) javax.IOException . this media might be removed by the user possibly at any time causing it to become unavailable.if the landmark store couldn’t be created due to an I/O error SecurityException . The category will be removed from all landmarks that are in that category.if the application does not have permissions to create a new landmark store LandmarkException33 .io.location Java application is not able to directly choose where the landmark store is stored.Landmark29 lm) throws IOException.microedition. Parameters: categoryName .if the name is too long or if a landmark store with the specified name already exists java. However. IOException Description: Removes a category from this LandmarkStore. Parameters: storeName . This method removes the specified landmark from all categories and deletes the information from this LandmarkStore. the method returns silently with no error.IOException .microedition. LandmarkException Description: Deletes a landmark from this LandmarkStore. If the landmark store is stored on a removable media.if the parameter is null LandmarkException33 . The Landmark instance passed in as the parameter must be an instance that belongs to this LandmarkStore.if the implementation does not support creating new landmark stores deleteCategory(String) Declaration: public void deleteCategory(String categoryName) throws LandmarkException.if an I/O error occurs SecurityException . 38 .the name of the landmark store to create Throws: NullPointerException . If a category with the supplied name does not exist in this LandmarkStore.location.g. A newly created landmark store does not contain any landmarks.if the application does not have the permission to manage categories deleteLandmark(Landmark) Declaration: public void deleteLandmark(javax.if the parameter is null IllegalArgumentException . if the implementation supports several storage media. There must be one default landmark store and there may be other landmark stores that can be accessed by name.if the application is not allowed to delete the landmark LandmarkException33 . getInstance(String) Declaration: public static javax. then the request is silently ignored and the method call returns with no error.util.the landmark to be deleted Throws: SecurityException .if the implementation does not support deleting landmark stores getCategories() Declaration: public java. If a landmark store with the specified name does not exist.if an I/O error happened when accessing the landmark store NullPointerException .Enumeration getCategories() Description: Returns the category names that are defined in this LandmarkStore.if the parameter is null (the default landmark store can’t be deleted) java. The language and locale used for these names depends on the implementation and end user settings.if the landmark store couldn’t be deleted due to an I/O error SecurityException .if the landmark instance passed as the parameter does not belong to this LandmarkStore java. LandmarkException Description: Delete a landmark store with a specified name. Parameters: lm . Returns: an java.if the appliction does not have permissions to delete a landmark store LandmarkException33 .io. Parameters: storeName .io.the name of the landmark store to create Throws: NullPointerException .Enumeration containing Strings representing the category names. 39 . If there are no categories defined in this LandmarkStore.microedition.location LandmarkStore deleteLandmarkStore(String) If the Landmark is not found in this LandmarkStore.IOException . this method returns silently without any error.microedition. The names shall be such that they can be displayed to the end user and have a meaning to the end user.location.IOException . deleting and retrieving landmarks.javax.util. an Enumeration with no entries is returned. All the landmarks and categories defined in the named landmark store are irrevocably removed.if the parameter is null deleteLandmarkStore(String) Declaration: public static void deleteLandmarkStore(String storeName) throws IOException.LandmarkStore35 getInstance(String storeName) Description: Gets a LandmarkStore instance for storing. the category of the landmark. Throws: SecurityException .location Parameters: storeName .LandmarkStore getLandmarks() javax.0.0). the default landmark store will be returned Returns: the LandmarkStore object representing the specified landmark store or null if a landmark store with the specified name does not exist.microedition. or if minLatitude > maxLatitude 40 . maxLongitude] and [minLongitude.util.minimum longitude of the area.IOException . double minLatitude.0. The bounds are considered to belong to the area.if the application does not have a permission to read landmark stores getLandmarks() Declaration: public java.maximum longitude of the area.Enumeration getLandmarks(String category.io.90.0] minLongitude . If minLongitude <= maxLongitude.util. 180.0. maxLongitude].Enumeration getLandmarks() throws IOException Description: Lists all landmarks stored in the store.0).minimum latitude of the area.0. Must be within the range [-180. or minLatitude or maxLatitude is out of the range [-90.if an I/O error happened when accessing the landmark store IllegalArgumentException .0) maxLongitude . double.0.0. the area covers the latitude range [minLatitude.Enumeration object containing Landmark objects representing all the landmarks stored in this LandmarkStore or null if there are no landmarks in the store Throws: java. double) Declaration: public java. 90. double. null implies a wildcard that matches all categories minLatitude . double maxLongitude) throws IOException Description: Lists all the landmarks that are within an area defined by bounding minimum and maximum latitude and longitude and belong to the defined category.0] maxLatitude .if the minLongitude or maxLongitude is out of the range [-180.io.if an I/O error happened when accessing the landmark store getLandmarks(String. 180. For latitude. if specified. Must be within the range [-90.0]. Returns: an java. double. Must be within the range [-180. double minLongitude.the name of the landmark store to open. 90. Parameters: category .IOException . this area covers the longitude range [minLongitude. maxLatitude].util. if null.0) Returns: an Enumeration containing all the matching Landmarks or null if no Landmark matched the given parameters Throws: java. Must be within the range [minLatitude. If minLongitude > maxLongitude. 180. this area covers the longitude range [-180. 180.maximum latitude of the area. double maxLatitude. String name) throws IOException Description: Gets the Landmarks from the storage where the category and/or name matches the given parameters.util. String) Declaration: public java. null implies a wildcard that matches all the names within the category indicated by the category parameter Returns: an Enumeration containing all the matching Landmarks or null if no Landmark matched the given parameters Throws: java. String category) throws IOException Description: Removes the named landmark from the specified category. The Landmark instance passed in as the parameter must be an instance that belongs to this LandmarkStore.IOException .if an I/O error happened when accessing the landmark store listLandmarkStores() Declaration: public static String[] listLandmarkStores() throws IOException Description: Lists the names of all the available landmark stores.Landmark29 lm. null implies a wildcard that matches all categories name . Parameters: category .io. If the Landmark is not found in this LandmarkStore in the specified category or if the parameter is a Landmark instance that does not belong to this LandmarkStore. The null name for the default landmark store is not included in the list returned by this method.if an I/O error occurred when trying to access the landmark stores removeLandmarkFromCategory(Landmark. other than the default landmark store.Enumeration getLandmarks(String category.location.microedition. this method returns null. Returns: an array of landmark store names Throws: SecurityException . The request is also silently ignored if the specified category does not exist in this LandmarkStore.the name of the desired landmark.microedition. String) Declaration: public void removeLandmarkFromCategory(javax.io. then the request is silently ignored and the method call returns with no error.javax.the category of the landmark. String) getLandmarks(String.if the application does not have the permission to access landmark stores java. If there are no named landmark stores. The default landmark store is obtained from getInstance by passing null as the parameter. 41 .IOException .location LandmarkStore getLandmarks(String. IOException . This method can’t be used to add a new landmark to the store.microedition. Parameters: lm .if the application is not allowed to update the landmark LandmarkException33 .if an I/O error happened when accessing the landmark store NullPointerException .Landmark29 lm) throws IOException.io.location. This method only updates the information about a landmark and does not modify the categories the landmark belongs to.if the landmark instance passed as the parameter does not belong to this LandmarkStore or does not exist in the store any more java.if an I/O error happened when accessing the landmark store NullPointerException . If the landmark no longer belongs to any category. LandmarkException Description: Updates the information about a landmark. Parameters: lm .IOException .the category from which it will be removed. The Landmark instance passed in as the parameter must be an instance that belongs to this LandmarkStore.location The landmark is only removed from the specified category but the landmark information is retained in the store.the landmark to be updated Throws: SecurityException . it can still be obtained from the store by passing null as the category to getLandmarks.the landmark to be removed category . Throws: SecurityException .microedition.if either parameter is null updateLandmark(Landmark) Declaration: public void updateLandmark(javax.io.LandmarkStore updateLandmark(Landmark) javax.if the parameter is null 42 .if the application is not allowed to delete the landmark java. it MUST ensure that it only returns objects where the parameters have values set as described for their semantics in this class. the getQualifiedCoordinates method may return either null or some coordinates where the information is not necessarily fully correct. All other bits in the 32 bit integer than those that have defined constants in this class are reserved and MUST not be set by implementations (i. This includes the timestamped coordinates. course. For an invalid Location object. This bit field is a bitwise combination of the location method technology bits (MTE_*).microedition. The validity can be queried using the isValid method. This class is only a container for the information. When the platform implementation returns Location objects. these bits must be 0). The periodic location updates to the LocationListener may return invalid Location objects if it isn’t possible to determine the location.location Location Declaration public class Location Object | +--javax.microedition.javax.Location Description The Location class represents the standard set of basic location information. plus an optional textual address. The location method is indicated using a bit field. accuracy.e. but the extra info that is obtained from the getExtraInfo method can provide information about the reason why it was not possible to provide a valid Location. A valid Location object represents a location with valid coordinates and the getQualifiedCoordinates method must return there coordinates. and information about the positioning method used for the location. Member Summary Fields static static static static static static static static static static int int int int int int int int int int MTA_ASSISTED44 MTA_UNASSISTED44 MTE_ANGLEOFARRIVAL44 MTE_CELLID45 MTE_SATELLITE45 MTE_SHORTRANGE45 MTE_TIMEDIFFERENCE45 MTE_TIMEOFARRIVAL45 MTY_NETWORKBASED45 MTY_TERMINALBASED46 Constructors protected Location()46 Methods 43 . An invalid Location object doesn’t have valid coordinates.location Location javax. method type (MTY_*) and method assistance information (MTA_*). speed.microedition.location. A Location object may be either ’valid’ or ’invalid’. The individual bits are defined using constants in this class. MTA_ASSISTED = 0x00040000 MTA_UNASSISTED Declaration: public static final int MTA_UNASSISTED Description: Location method is unassisted.Location MTA_ASSISTED javax. MTE_ANGLEOFARRIVAL = 0x00000020 44 . notify(). Only one of these bits may be set or neither to indicate that the assistance information is not known. MTA_UNASSISTED = 0x00080000 MTE_ANGLEOFARRIVAL Declaration: public static final int MTE_ANGLEOFARRIVAL Description: Location method Angle of Arrival for cellular / terrestrial RF system. hashCode(). Network assisted for terminal based).String int QualifiedCoordinates float long boolean getAddressInfo()46 getCourse()46 getExtraInfo(String mimetype)46 getLocationMethod()47 getQualifiedCoordinates()48 getSpeed()48 getTimestamp()48 isValid()48 Inherited Member Summary Methods inherited from class Object equals(Object).microedition. This bit and MTA_ASSISTED bit MUST NOT both be set. toString(). wait(). wait() Fields MTA_ASSISTED Declaration: public static final int MTA_ASSISTED Description: Location method is assisted by the other party (Terminal assisted for Network based. getClass().lang.location Member Summary AddressInfo float java. notifyAll(). wait(). Bluetooth LP). MTE_SHORTRANGE = 0x00000010 MTE_TIMEDIFFERENCE Declaration: public static final int MTE_TIMEDIFFERENCE Description: Location method Time Difference for cellular / terrestrial RF system (for example. Only one of these bits may be set or neither to indicate that it is not known where the result is calculated.location Location MTE_CELLID MTE_CELLID Declaration: public static final int MTE_CELLID Description: Location method Cell-ID for cellular (in GSM. MTY_NETWORKBASED = 0x00020000 45 . MTE_TIMEDIFFERENCE = 0x00000002 MTE_TIMEOFARRIVAL Declaration: public static final int MTE_TIMEOFARRIVAL Description: Location method Time of Arrival (TOA) for cellular / terrestrial RF system. Cell Global Identity). MTE_SATELLITE = 0x00000001 MTE_SHORTRANGE Declaration: public static final int MTE_SHORTRANGE Description: Location method Short-range positioning system (for example. this is the same as CGI. Global Positioning System (GPS)).microedition. MTE_CELLID = 0x00000008 MTE_SATELLITE Declaration: public static final int MTE_SATELLITE Description: Location method using satellites (for example. MTE_TIMEOFARRIVAL = 0x00000004 MTY_NETWORKBASED Declaration: public static final int MTY_NETWORKBASED Description: Location method is of type network based. This means that the final location result is calculated in the network.javax. Enhanced Observed Time Difference (E-OTD) for GSM). This bit and MTY_TERMINALBASED bit MUST NOT both be set. NaN if the course is not known getExtraInfo(String) Declaration: public String getExtraInfo(String mimetype) 46 . MTY_TERMINALBASED = 0x00010000 Constructors Location() Declaration: protected Location() Description: A protected constructor for the Location to allow implementations of LocationProviders to construct the Location instances. This means that the final location result is calculated in the terminal.location. If no address is available.0.microedition. This constructor sets the fields to implementation specific default values.0) degrees.location MTY_TERMINALBASED Declaration: public static final int MTY_TERMINALBASED Description: Location method is of type terminal based. null is returned. The value is always in the range [0.Location MTY_TERMINALBASED javax.360. Returns: an AddressInfo associated with this Location object getCourse() Declaration: public float getCourse() Description: Returns the terminal’s course made good in degrees relative to true north. Methods getAddressInfo() Declaration: public javax.AddressInfo10 getAddressInfo() Description: Returns the AddressInfo associated with this Location object.microedition. Returns: the terminal’s course made good in degrees relative to true north or Float. Location providers are expected to set the fields to the correct values after constructing the object instance. This method is not intended to be used by applications. the returned value may have several MTE_* bits set. When the MIME type is “application/X-jsr179-location-lif”. it returns the extra information as a String encoded according to format identified by the MIME type. method type and assistance information. the method returns null. the returned string shall be a valid sequence of NMEA sentences formatted according to the syntax specified in the NMEA 0183 v3. The following MIME types are defined here together with their definitions in order to ensure interoperability of implementations wishing to use these types. The returned value is a bitwise combination (OR) of the method technology. null if the information for the requested MIME type is not available or not supported by this implementation. If the implementation supports this type. The definition of these types here is not an indication that these formats are preferred over any other format not defined here. the returned string shall contain an XML formatted document containing the “pd” element defined in the LIF Mobile Location Protocol TS 101 v3.microedition. For example. Other bits are reserved and must be set to 0.the MIME type of the requested extra information Returns: string encoded according to the format identified by the MIME type defined in the parameter.location Location getLocationMethod() Description: Returns extra information about the location.0. This method is intended to provide location method specific extra information that applications that are aware of the used location method and information format are able to use. If the location is determined by combining several location technologies. the returned string shall contain textual extra information that can be displayed to the end user. the returned value must have all the bits set to zero. If the implementation does not support this type. Parameters: mimetype .0 as the root element of the document. the method type values are named MTY_* and assistance information values are named MTA_*.javax. Only bits that have defined constants within this class are allowed to be used. The method technology values are defined as constant values named MTE_* in this class. A MIME type is used to identify the type of the extra information when requesting it. Returns: a bitfield identifying the used location method 47 .1 specification. if the location method used is terminal based. When the MIME type is “text/plain”. If the used location method is unknown. network assisted E-OTD. getLocationMethod() Declaration: public int getLocationMethod() Description: Returns information about the location method used. These sentences shall represent the set of NMEA sentences that are related to this location at the time this location was created. the value 0x00050002 ( = MTY_TERMINALBASED | MTA_ASSISTED | MTE_TIMEDIFFERENCE) would be returned. When the MIME type is “application/X-jsr179-location-nmea”. This specification does not require implementations to support any extra information type. microedition. Implementations make best effort to set the timestamp as close to this point in time as possible. Returns: the current ground speed in m/s for the terminal or Float.QualifiedCoordinates65 getQualifiedCoordinates() Description: Returns the coordinates of this location and their accuracy. Returns: a boolean value with true indicating that this Location instance is valid and false indicating an invalid Location instance See Also: getExtraInfo(String)46 48 . This timestamp should represent the point in time when the measurements were made.NaN if the speed is not known getTimestamp() Declaration: public long getTimestamp() Description: Returns the time stamp at which the data was collected.Location getQualifiedCoordinates() javax. especially the latitude and longitude coordinates.location.location getQualifiedCoordinates() Declaration: public javax. returns null. Returns: a QualifiedCoordinates object. The time returned is the time of the local clock in the terminal in milliseconds using the same clock and same time representation as System.microedition. getSpeed() Declaration: public float getSpeed() Description: Returns the terminal’s current ground speed in meters per second (m/s) at the time of measurement.currentTimeMillis() isValid() Declaration: public boolean isValid() Description: Returns whether this Location instance represents a valid location with coordinates or an invalid one where all the data. Note that unlike the coordinates.currentTimeMillis(). The speed is always a non-negative value. If the coordinates are not known. may not be present. speed does not have an associated accuracy because the methods used to determine the speed typically are not able to indicate the accuracy. A valid Location object contains valid coordinates whereas an invalid Location object may not contain valid coordinates but may contain other information via the getExtraInfo() method to provide information on why it was not possible to provide a valid Location object. Returns: a timestamp representing the time See Also: System. microedition.javax.microedition. 49 . wait(). Member Summary Constructors LocationException()49 LocationException(String s)50 Inherited Member Summary Methods inherited from class Object equals(Object). wait().location LocationException javax.microedition. toString() Constructors LocationException() Declaration: public LocationException() Description: Constructs a LocationException with no detail message. printStackTrace(). notifyAll(). getClass(). notify(). The detailed conditions when this exception is thrown are documented in the methods that throw this exception. hashCode().LocationException Description The LocationException is thrown when a location API specific error has occurred.location.location LocationException Declaration public class LocationException extends Exception Object | +--Throwable | +--Exception | +--javax. wait() Methods inherited from class Throwable getMessage(). Parameters: s .location LocationException(String) Declaration: public LocationException(String s) Description: Constructs a LocationException with the specified detail message.LocationException LocationException(String) javax.microedition.the detail message 50 . location. If it isn’t possible to determine the location.LocationProvider53 provider. The application is responsible for any possible synchronization needed in the listener methods. Applications implement this interface and register it with a LocationProvider to obtain regular position updates. Location) javax. Location) Declaration: public void locationUpdated(javax. When the listener is registered with a LocationProvider with some update period.microedition.microedition. See Also: LocationProvider53.location LocationListener locationUpdated(LocationProvider.g. but this timing is not guaranteed to be very exact (i.location. int newState)52 Methods locationUpdated(LocationProvider. Location43 Member Summary Methods void locationUpdated(LocationProvider provider.Location43 location) Description: Called by the LocationProvider to which this listener is registered. the implementation can send an update to the listener that contains an ’invalid’ Location instance.e. This method will be called periodically according to the interval defined when registering the listener to provide updates of the current location. Application should do any necessary extensive processing in a separate thread and only use these methods to initiate the processing. javax. Location location)51 void providerStateChanged(LocationProvider provider.microedition. 51 . e.location LocationListener Declaration public interface LocationListener Description The LocationListener represents a listener that receives events associated with a particular LocationProvider. The method calls are intended as triggers to the application.microedition. the implementation shall attempt to provide updates at the defined interval. this is not an exact timer facility for an application). The listener methods MUST return quickly and should not perform any extensive processing.javax. because of the LocationProvider being TEMPORARILY_UNAVAILABLE or OUT_OF_SERVICE or because the update period is too frequent for the location method to provide updates. The implementation shall use best effort to post the location updates at the specified interval. i.LocationProvider53 provider. If the application is subscribed to receive periodic location updates. int) Declaration: public void providerStateChanged(javax.LocationListener javax. the new position providerStateChanged(LocationProvider.microedition.location.the source of the event newState .e. it should de-register itself from the provider.microedition.the new state of the LocationProvider. Parameters: provider .the source of the event location . it will continue to receive these regardless of the state of the LocationProvider. This value is one of the constants for the state defined in the LocationProvider class. int) Parameters: provider .location providerStateChanged(LocationProvider. int newState) Description: Called by the LocationProvider to which this listener is registered if the state of the LocationProvider has changed. The timing of these events is not related to the period of the location updates. 52 . If the application wishes to stop receiving location updates for an unavailable provider. These provider state changes are delivered to the application as soon as possible after the state of a provider changes.the location to which the event relates. location LocationProvider javax. It is the responsibility of the implementation to return the correct LocationProvider-derived object.microedition.javax.location. A LocationProvider represents a location-providing module. generating Locations. Applications that need to specify criteria for the location provider selection. The methods that access the location related information shall throw SecurityException if the application does not have the relevant permission to access the location information. float proximityRadius)55 static getInstance(Criteria criteria)55 LocationProvider static Location getLastKnownLocation()56 abstract Location getLocation(int timeout)57 abstract int getState()57 static void removeProximityListener(ProximityListener listener)57 abstract void reset()58 abstract void setLocationListener(LocationListener listener. int maxAge)58 53 . and pass it to the factory method.LocationProvider Description This is the starting point for applications using this API and represents a source of the location information. Member Summary Fields static int AVAILABLE54 static int OUT_OF_SERVICE54 static int TEMPORARILY_UNAVAILABLE54 Constructors protected LocationProvider()54 Methods static void addProximityListener(ProximityListener listener. must first create a Criteria object.microedition. Applications obtain LocationProvider instances (classes implementing the actual functionality by extending this abstract class) by calling the factory method.microedition.location LocationProvider Declaration public abstract class LocationProvider Object | +--javax. int timeout. int interval. Coordinates coordinates. 54 . notify(). Being out of service means that the method is unavailable and the implementation is not able to expect that this situation would change in the near future. However. OUT_OF_SERVICE Declaration: public static final int OUT_OF_SERVICE Description: Availability status code: the location provider is out of service. TEMPORARILY_UNAVAILABLE Declaration: public static final int TEMPORARILY_UNAVAILABLE Description: Availability status code: the location provider is temporarily unavailable.location Inherited Member Summary Methods inherited from class Object equals(Object). hashCode().microedition. when deep inside a building for satellite based methods. wait() Fields AVAILABLE Declaration: public static final int AVAILABLE Description: Availability status code: the location provider is available. Applications should not make subclasses of this class and invoke this constructor from the subclass. wait(). toString(). a very short transient obstruction of the signal should not cause the provider to toggle quickly between TEMPORARILY_UNAVAILABLE and AVAILABLE.LocationProvider AVAILABLE javax. This is not intended to be used by applications. An example is not being able to receive the signal because the signal used by the location method is currently being obstructed.g. wait(). Temporary unavailability means that the method is unavailable due to reasons that can be expected to possibly change in the future and the provider to become available. getClass(). An example is when using a location method implemented in an external device and the external device is detached. Constructors LocationProvider() Declaration: protected LocationProvider() Description: Empty constructor to help implementations and extensions. notifyAll(). e. If the implementation is capable of supporting the proximity monitoring and has resources to add the new listener and coordinates to be monitored but the monitoring can’t be currently done due to the current state of the method used to implement it.the coordinates to be registered proximityRadius .if the proximity radius is 0 or negative* or Float. Coordinates.microedition.location.LocationProvider53 getInstance(javax.microedition. float) Declaration: public static void addProximityListener(javax.microedition. the listener shall be called immediately. Detecting the proximity to the defined coordinates is done on a best effort basis by the implementation. Coordinates. float proximityRadius) throws LocationException Description: Adds a ProximityListener for updates when proximity to the specified coordinates is detected.location.Coordinates16 coordinates.location.microedition.javax. it is possible that the implementation misses this. If the current location is known to be within the proximity radius of the specified coordinates.if the platform does not have resources to add a new listener and coordinates to be monitored or does not support proximity monitoring at all IllegalArgumentException . javax.Criteria22 criteria) throws LocationException 55 . If this method is called with a ProximityListener that is already registered.microedition. there are no guarantees that the proximity is always detected.location.the listener to be registered coordinates . float) Methods addProximityListener(ProximityListener. A single listener can handle events for multiple sets of coordinates.if the listener or coordinates parameter is null SecurityException .NaN NullPointerException . the registration to the specified coordinates is added in addition to the set of coordinates it has been previously registered for.location LocationProvider addProximityListener(ProximityListener. especially in situations where the terminal briefly enters the proximity area and exits it shortly afterwards. this method shall succeeed and the monitoringStateChanged method of the listener shall be immediately called to notify that the monitoring is not active currently. Parameters: listener .ProximityListener63 listener. Due to the limitations of the methods used to implement this.the radius in meters that is considered to be the threshold for being in the proximity of the specified coordinates Throws: LocationException49 .if the application does not have the permission to register a proximity listener getInstance(Criteria) Declaration: public static javax. It is optional to provide this feature as it may not be reasonably implementable with all methods used to implement this API. microedition. it shall not be returned. if the same instance can be used to fulfil both defined criteria. Parameters: criteria . if all supported location providers are out of service. This is the best estimate that the implementation has for the previously known location. the least restrictive criteria possible).location.e. 56 . The LocationException is thrown. If no concrete LocationProvider could be created that typically can match the defined criteria but there are other location providers not meeting the criteria that could be returned for a more relaxed criteria. Applications can use this method to obtain the last known location and check the timestamp and other fields to determine if this is recent enough and good enough for the application to use without needing to make a new request for the current location.microedition. Passing null as the parameter is equal to passing a Criteria that has all fields set to the default values. i. depending on the implementation.the criteria for provider selection or null to indicate the least restrictive criteria with default values Returns: a LocationProvider meeting the defined criteria or null if a LocationProvider that meets the defined criteria can’t be returned but there are other supported available or temporarily unavailable providers that do not meet the criteria. A LocationProvider instance is returned if there is a location provider meeting the criteria in either the available or temporarily unavailable state. The implementation chooses the LocationProvider so that it best fits the defined criteria.Location43 getLastKnownLocation() Description: Returns the last known location that the implementation has. Throws: LocationException49 . null is returned to indicate this. This method may. but this can’t be always guaranteed because the implementation may not always know the state correctly at this point in time.location Description: This factory method is used to get an actual LocationProvider implementation based on the defined criteria.LocationProvider getLastKnownLocation() javax.e. the implementation shall return a LocationProvider if there is any provider that isn’t in the out of service state. When this method is called with a Criteria that has all fields set to the default values (i. the least restrictive set of criteria. Note that there can be only one LocationListener associated with a LocationProvider instance. If a LocationProvider meeting the criteria can be supported but is currently out of service. Implementations should try to select providers in the available state before providers in temporarily unavailable state. Any possible initialization of the provider is done at an implementation dependent time and MUST NOT block the call to this method. return the same LocationProvider instance as has been returned previously from this method to the calling application. taking into account also possible implementation dependent preferences of the end user.if all LocationProviders are currently out of service See Also: Criteria22 getLastKnownLocation() Declaration: public static javax. This method only makes the selection of the provider based on the criteria and is intended to return it quickly to the application. microedition. the implementation shall wait and try to obtain the location until the timeout expires. Parameters: timeout . The Criteria is used to select a location provider that typically is able to meet the defined criteria. If the provider is temporarily unavailable. The return value shall be one of the availability status code constants defined in this class.if the calling application does not have a permission to query the location information IllegalArgumentException . Returns: a Location object Throws: LocationException49 . If no result could be retrieved.if the operation is interrupted by calling reset() from another thread SecurityException .microedition. InterruptedException Description: Retrieves a Location with the constraints given by the Criteria associated with this class.location.ProximityListener63 listener) 57 . If the provider is out of service.location. Note that the individual Location returned might not fulfil exactly the criteria used for selecting this LocationProvider. If the location can’t be determined within the timeout period specified in the parameter.Location43 getLocation(int timeout) throws LocationException.javax.a timeout value in seconds. Returns: the availability state of this LocationProvider removeProximityListener(ProximityListener) Declaration: public static void removeProximityListener(javax.if the location couldn’t be retrieved or if the timeout period expired InterruptedException .if the timeout = 0 or timeout < -1 getState() Declaration: public abstract int getState() Description: Returns the current state of this LocationProvider. Throws: SecurityException . -1 is used to indicate that the implementation shall use its default timeout value for this provider.location LocationProvider getLocation(int) Returns: a location object.microedition. a LocationException is thrown. but not necessarily for every individual location measurement.if the calling application does not have a permission to query the location information getLocation(int) Declaration: public abstract javax. null is returned if the implementation doesn’t have any previous location information. the method shall throw a LocationException. then the LocationException is thrown immediately. LocationListener51 listener. when exiting to have its threads freed from blocking synchronous operations. This is also done if the reason for the inability to obtain a new location result is due to the provider being temporarily unavailable or out of service. Setting the listener replaces any possibly previously set listener. the update will be made and an invalid Location instance is returned. Passing in -1 as the interval selects the default interval which is dependent on the used location method. int maxAge) Description: Adds a LocationListener for updates at the defined interval. The implementation shall initiate obtaining the first location result immediately when the listener is registered and provide the location to the listener as soon as it is available. Only one listener can be registered with each LocationProvider instance. The listener also gets updates when the availablilty state of the LocationProvider changes.g. Parameters: listener . int.location Description: Removes a ProximityListener from the list of recipients for updates.location. For example. If it’s not possible to get a new location result (interval + timeout) seconds after the previous update. int) Declaration: public abstract void setLocationListener(javax.microedition. int timeout.if the parameter is null reset() Declaration: public abstract void reset() Description: Resets the LocationProvider.microedition. Subsequent location updates will happen at the defined interval after the first one.the listener to remove Throws: NullPointerException . the update must be delivered at 58 . If the specified update interval is smaller than the time it takes to obtain the first result. All pending synchronous location requests will be aborted and any blocked getLocation method calls will terminate with InterruptedException. If the specified listener is not registered or if the parameter is null. the listener shall receive location updates with invalid Locations at the defined interval until the first location result is available. Setting the listener to null cancels the registration of any previously set listener. The listener will be called with updated location at the defined interval. Applications can use this method e. This timeout value indicates how many seconds the update is allowed to be provided late compared to the defined interval. int. setLocationListener(LocationListener. if the interval is 60 seconds and the timeout is 10 seconds.LocationProvider reset() javax. The timeout parameter determines a timeout that is used if it’s not possible to obtain a new location result when the update is scheduled to be provided. int interval. Passing in 0 as the interval registers the listener to only receive provider status updates and not location updates at all. this method silently returns with no action. the default timeout for this provider is used.if interval < -1. if the value is -1.the listener to be registered. maxAge . Also. the value of this parameter has no effect and the default maximum age for this provider is used. Also. -1 is used for the default interval of this provider. if the interval is -1 to indicate the default. 0 is used to indicate that the application wants to receive only provider status updates and not location updates at all. this parameter has no effect. If the interval is 0. if the interval is 60 seconds. This parameter can only be used to indicate a larger value than the normal time of obtaining a location result by a location method. or if (interval != -1) and (timeout > interval or maxAge > interval or (timeout < 1 and timeout != -1) or (maxAge < 1 and maxAge != -1)) SecurityException . the value of this parameter has no effect and the default timeout for this provider is used. this parameter has no effect.microedition. Throws: IllegalArgumentException . int. interval . timeout . then the maxAge setting to 20 seconds allows to return this result and not start obtaining a new one.if the calling application does not have a permission to query the location information 59 . the implementation would normally start obtaining the result 50 seconds after the previous update. int. if the interval is -1 to indicate the default.maximum age of the returned location in seconds.timeout value in seconds. If there is a location result otherwise available that is more recent than 40 seconds after the previous update. If set to null the registration of any previously set listener is cancelled. must be greater than 0 or equal to -1 to indicate that the default maximum age for this provider is used. the implementation shall provide as recent location results as are possible with the used location method. must be greater than 0. If the application specifies a time value that is less than what can be realized with the used location method. If the interval is 0.the interval in seconds. For example. This allows the implementation to reuse location results if it has a recent location result when the update is due to be delivered. The normal time of obtaining the location result means the time it takes normally to obtain the result when a request is made. int) most 70 seconds after the previous update and if no new location result is available by that time the update will be made with an invalid Location instance. The maxAge parameter defines how old the location result is allowed to be provided when the update is made.javax. Parameters: listener .location LocationProvider setLocationListener(LocationListener. the maxAge is 20 seconds and normal time to obtain the result is 10 seconds. Orientation Description The Orientation class represents the physical orientation of the terminal. This class is only a container for the information. It is not expected that all terminals will support all of these parameters. Member Summary Constructors Orientation(float azimuth. No accuracy data is given for Orientation. pitch (the vertical elevation angle) and roll (the rotation of the terminal around its own longitudinal axis).microedition.location javax. Orientation is described by azimuth to north (the horizontal pointing direction). This means that the pitch is positive when the top of the screen is up and the bottom of the screen down (when roll is zero). It is up to the terminal to define its own axes. this class will be used to obtain the current compass direction. When the platform implementation returns Orientation objects.Orientation javax. but it is generally recommended that the longitudinal axis is aligned with the bottom-to-top direction of the screen. float roll)61 Methods float static Orientation float float boolean getCompassAzimuth()61 getOrientation()61 getPitch()62 getRoll()62 isOrientationMagnetic()62 Inherited Member Summary Methods inherited from class Object 60 . when the left side of the screen is up and the right side of the screen is down (when pitch is zero). If a terminal supports getting the Orientation. boolean isMagnetic.microedition. it MUST ensure that it only returns objects where the parameters have values set as described for their semantics in this class.location.location Orientation Declaration public class Orientation Object | +--javax. i. Most commonly. Providing the pitch and roll is optional. The roll is positive when the device is tilted clockwise looking from the direction of the bottom of the screen.microedition.e. it MUST provide the compass azimuth information. The get* methods return the values passed in the constructor. float pitch. The constructor does not validate the parameters passed in but just retains the values. the roll of the terminal in degrees. The isOrientationMagnetic() method indicates whether the returned azimuth is relative to true north or magnetic north.location Orientation Orientation(float. float pitch. 90.0 west.the pitch of the terminal in degrees. 61 . getClass(). The value is always in the range [0. The values are expressed in degress using floating point values.javax. wait().0 east. Returns: the terminal’s compass azimuth in degrees relative to true or magnetic north See Also: isOrientationMagnetic()62 getOrientation() Declaration: public static javax. 90.a boolean stating whether the compass azimuth is given as relative to the magnetic field of the Earth (=true) or to true north and gravity (=false) pitch .0. pitch and roll parameters specified. wait(). Parameters: azimuth . Valid range: [0. notify().location. float. For example. 360.0) degrees. 180. boolean.0 indicates north.microedition. isMagnetic . float) Inherited Member Summary equals(Object). boolean. value 0. float) Declaration: public Orientation(float azimuth. Valid range: [-180. wait() Constructors Orientation(float.the compass azimuth relative to true or magnetic north.0. float roll) Description: Constructs a new Orientation object with the compass azimuth. Valid range: [-90. notifyAll(). hashCode().microedition.0).Orientation60 getOrientation() throws LocationException Description: Returns the terminal’s current orientation.0.0 south and 270. 180.0) Methods getCompassAzimuth() Declaration: public float getCompassAzimuth() Description: Returns the terminal’s horizontal compass azimuth in degrees relative to either magnetic or true north.NaN. 360. If the pitch or roll is undefined.0] roll . toString(). boolean isMagnetic. float.0. the parameter shall be given as Float. microedition.if the implementation does not support orientation determination SecurityException . Returns: the terminal’s roll in degrees or Float. If this method returns true.Orientation getPitch() javax. the compass azimuth is relative to true north and pitch is relative to gravity. Returns: the terminal’s pitch in degrees or Float. 180.0.0] degrees. 90.0. false if this Orientation is relative to true north and gravity See Also: getCompassAzimuth()61 62 .if the calling application does not have a permission to query the orientation See Also: Orientation60 getPitch() Declaration: public float getPitch() Description: Returns the terminal’s tilt in degrees defined as an angle in the vertical plane orthogonal to the ground. The value is always in the range [-90. looking from direction of the bottom of the screen.NaN if not available getRoll() Declaration: public float getRoll() Description: Returns the terminal’s rotation in degrees around its own longitudinal axis. Returns: true if this Orientation is relative to the magnetic field of the Earth.NaN if not available isOrientationMagnetic() Declaration: public boolean isOrientationMagnetic() Description: Returns a boolean value that indicates whether this Orientation is relative to the magnetic field of the Earth or relative to true north and gravity. If this method returns false. A negative value means that the terminal is orientated anti-clockwise from its default orientation. the compass azimuth and pitch are relative to the magnetic field of the Earth. and through the longitudinal axis of the terminal. The value is always in the range [-180. A negative value means that the top of the terminal screen is pointing towards the ground.location Returns: returns an Orientation object containing the terminal’s current orientation or null if the orientation can’t be currently determined Throws: LocationException49 .0) degrees. 63 .removeProximityListener or the application exits. Regardless of the state. Location location)64 Methods monitoringStateChanged(boolean) Declaration: public void monitoringStateChanged(boolean isMonitoringActive) Description: Called to notify that the state of the proximity monitoring has changed. true indicates that the proximity monitoring is active and false indicates that the proximity monitoring can’t be done currently. The proximity is defined as the proximity radius around the coordinates combined with the horizontal accuracy of the current sampled location.javax. it must re-register the coordinates and the listener. These state changes are delivered to the application as soon as possible after the state of the monitoring changes.microedition.microedition. Applications implement this interface and register it with a static method in LocationProvider to obtain notfications when proximity to registered coordinates is detected.location ProximityListener monitoringStateChanged(boolean) javax. These state changes may be related to state changes of some location providers.a boolean indicating the new state of the proximity monitoring. Parameters: isMonitoringActive . If the application wants to be notified again about these coordinates. the ProximityListener remains registered until the application explicitly removes it with LocationProvider. but this is implementation dependent as implementations can freely choose the method used to implement this proximity monitoring. Member Summary Methods void monitoringStateChanged(boolean isMonitoringActive)63 void proximityEvent(Coordinates coordinates. This listener is called when the terminal enters the proximity of the registered coordinates. The registration with these coordinates is cancelled when the listener is called.location ProximityListener Declaration public interface ProximityListener Description This interface represents a listener to events associated with detecting proximity to some registered coordinates. The listener is called only once when the terminal enters the proximity of the registered coordinates. Location) javax.microedition.microedition. Parameters: coordinates .Coordinates16 coordinates.the current location of the terminal 64 .location proximityEvent(Coordinates. this method will be called by the platform when the implementation detects that the current location of the terminal is within the defined proximity radius of the registered coordinates. Location) Declaration: public void proximityEvent(javax.ProximityListener proximityEvent(Coordinates.microedition. javax.Location43 location) Description: After registering this listener with the LocationProvider.location.the registered coordinates to which proximity has been detected location .location. javax. toString(). float horizontalAccuracy. int)18.Coordinates16 | +--javax. hashCode(). int)18.QualifiedCoordinates Description The QualifiedCoordinates class represents coordinates as latitude-longitude-altitude values that are associated with an accuracy value. wait() 65 . getAltitude()20.location. getClass(). float altitude. getLongitude()20. convert(double. getLatitude()20.microedition. convert(double. float verticalAccuracy)66 Methods float float void void getHorizontalAccuracy()66 getVerticalAccuracy()66 setHorizontalAccuracy(float horizontalAccuracy)67 setVerticalAccuracy(float verticalAccuracy)67 Inherited Member Summary Fields inherited from class Coordinates16 DD_MM17. distance(Coordinates)19.microedition. setLatitude(double)21.location.microedition. notifyAll(). notify(). setLongitude(double)21 Methods inherited from class Object equals(Object).microedition. Member Summary Constructors QualifiedCoordinates(double latitude.location QualifiedCoordinates javax. wait(). DD_MM_SS17 Methods inherited from class Coordinates16 azimuthTo(Coordinates)18. wait().location QualifiedCoordinates Declaration public class QualifiedCoordinates extends Coordinates16 Object | +--javax. double longitude. setAltitude(float)20. 1sigma standard deviation). Must be greater or equal to 0. Valid range: [-180. A value of Float.NaN can be used to indicate that the accuracy is not known. float. Valid range: [-90.NaN means the horizontal accuracy could not be determined. float. Float.microedition.NaN can be used to indicate that altitude is not known. 1-sigma). double.the altitude of the location in meters. Float.QualifiedCoordinates javax. double longitude.0] longitude .if an input parameter is out of the valid range Methods getHorizontalAccuracy() Declaration: public float getHorizontalAccuracy() Description: Returns the horizontal accuracy of the location in meters (1-sigma standard deviation). The horizontal accuracy is the RMS (root mean square) of east accuracy (latitudinal error in meters. verticalAccuracy . north accuracy (longitudinal error in meters.NaN can be used to indicate that the accuracy is not known.the latitude of the location.NaN value can be used for altitude to indicate that altitude is not known. float) Declaration: public QualifiedCoordinates(double latitude.location QualifiedCoordinates(double. defined as height above WGS84 ellipsoid. 90. Must be greater or equal to 0.the vertical accuracy of this location result in meters. Throws: IllegalArgumentException . Parameters: latitude . 180. The Float. Returns: the horizontal accuracy in meters. float verticalAccuracy) Description: Constructs a new QualifiedCoordinates object with the values specified. float.the horizontal accuracy of this location result in meters.the longitude of the location. horizontalAccuracy . The degrees are in decimal values (rather than minutes/seconds). float horizontalAccuracy. The latitude and longitude parameters are expressed in degrees using floating point values. Float. The coordinate values always apply to the WGS84 datum.0. double. Float.NaN if this is not known getVerticalAccuracy() Declaration: public float getVerticalAccuracy() 66 .0) altitude . float. float) Constructors QualifiedCoordinates(double.0. float altitude. Returns: the vertical accuracy in meters.if the parameter is less than 0 setVerticalAccuracy(float) Declaration: public void setVerticalAccuracy(float verticalAccuracy) Description: Sets the accuracy of the location in meters in vertical direction (orthogonal to ellipsoid surface. Must be greater or equal to 0. Float.the horizontal accuracy of this location result in meters.microedition.NaN means the horizontal accuracy could not be determined. The horizontal accuracy is the RMS (root mean square) of east accuracy (latitudinal error in meters.NaN means the horizontal accuracy could not be determined.if the parameter is less than 0 67 . Float. Must be greater or equal to 0. Throws: IllegalArgumentException . 1-sigma).NaN means the vertical accuracy could not be determined.javax. 1sigma standard deviation). Parameters: verticalAccuracy . Throws: IllegalArgumentException .location QualifiedCoordinates setHorizontalAccuracy(float) Description: Returns the accuracy of the location in meters in vertical direction (orthogonal to ellipsoid surface.NaN means the vertical accuracy could not be determined. Parameters: horizontalAccuracy . setHorizontalAccuracy(float) Declaration: public void setHorizontalAccuracy(float horizontalAccuracy) Description: Sets the horizontal accuracy of the location in meters (1-sigma standard deviation). A value of Float.NaN if this is not known. 1-sigma standard deviation).the vertical accuracy of this location result in meters. 1-sigma standard deviation).NaN means the horizontal accuracy could not be determined. Float. A value of Float. A value of Float. north accuracy (longitudinal error in meters. location .QualifiedCoordinates setVerticalAccuracy(float) 68 javax.microedition. * javax.CHA P TER 3 Constant Field Values Contents • javax.microedition.*5 javax.microedition.location.AddressInfo static int BUILDING_FLOOR11 11 static int BUILDING_NAME12 10 static int BUILDING_ROOM12 12 static int BUILDING_ZONE12 13 static int CITY12 4 static int COUNTRY12 7 static int COUNTRY_CODE12 8 static int COUNTY12 5 static int CROSSING113 14 static int CROSSING213 15 static int DISTRICT13 9 static int EXTENSION13 1 static int PHONE_NUMBER13 17 static int POSTAL_CODE13 3 static int STATE13 6 static int STREET14 2 static int URL14 16 69 .microedition. microedition.Coordinates static int DD_MM17 2 static int DD_MM_SS17 1 javax.javax.Criteria static int NO_REQUIREMENT23 0 static int POWER_USAGE_HIGH24 3 static int POWER_USAGE_LOW24 1 static int POWER_USAGE_MEDIUM24 2 javax.location.microedition.location.microedition.Location static int MTA_ASSISTED44 262144 static int MTA_UNASSISTED44 524288 static int MTE_ANGLEOFARRIVAL44 32 static int MTE_CELLID45 8 static int MTE_SATELLITE45 1 static int MTE_SHORTRANGE45 16 static int MTE_TIMEDIFFERENCE45 2 static int MTE_TIMEOFARRIVAL45 4 static int MTY_NETWORKBASED45 static int MTY_TERMINALBASED46 131072 65536 javax.microedition.location.LocationProvider 70 static int AVAILABLE54 1 static int OUT_OF_SERVICE54 3 static int TEMPORARILY_UNAVAILABLE54 2 .location. 71 . and on the same line as. Name of the constructor. which indicates the version in which the item was introduced. 6. Inheritance hierarchy. 2. The first column above is for the value of the @since comment. 8. In this example. the member is public.3 javax. Name of the package containing the class or interface. Modifiers ❍ abstract ● final ❏ static ■ static final Access Modifiers ♦protected Constructors and Fields ❉ constructor ✍ field 7. interface. RealtimeThread extends Thread. 4. Nested classes are listed in 1. Interfaces are italic. In this example. not here. Name of the class. 5. (Private and package-private modifiers also have no symbols.3 1. 72 . ➊➘ ➋➘ RealtimeThread ➌➙ ➥ Thread ➥ RealtimeThread ➎➘ ➏➘ 1. Implemented interfaces.ALMANAC LEGEND The almanac presents classes and intefaces in alphabetic order. and RealtimeThread implements Schedulable. If the “protected” symbol does not appear. 3.) One symbol from each group can appear in this column. Return type of a method or declared type of a field. nested class or nested interface. Thread implements Runnable.realtime Object ❏ ❉ ❉ ❏ ➍➙ Runnable Schedulable void addToFeasibility() RealtimeThread currentRealtimeThread() Scheduler getScheduler() RealtimeThread() RealtimeThread(SchedulingParameters scheduling) void sleep(Clock clock. Blank for constructors. the class that implements it. The second column above is for the following icons. field or method. This almanac is modeled after the style introduced by Patrick Chan in his excellent book Java Developers Almanac. which extends Object. HighResolutionTime time) ➚ ➚ throws InterruptedException ➐ ➑ 1. regardless of their package. The interface is to the right of. Fields. methods and constructors are in alphabetic order in a single list. microedition.location Object ➥Coordinates float azimuthTo(Coordinates to) ❏ ❏ ❉ ✍■ ✍■ String convert(double coordinate.location AddressInfo() int BUILDING_FLOOR int BUILDING_NAME int BUILDING_ROOM int BUILDING_ZONE int CITY int COUNTRY int COUNTRY_CODE int COUNTY int CROSSING1 int CROSSING2 int DISTRICT int EXTENSION String getField(int field) ✍■ ✍■ int PHONE_NUMBER int POSTAL_CODE void setField(int field. double longitude.Almanac AddressInfo Object ➥AddressInfo ❉ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ javax. float altitude) int DD_MM int DD_MM_SS float distance(Coordinates to) float getAltitude() 73 . String value) ✍■ ✍■ ✍■ int STATE int STREET int URL Coordinates javax.microedition. int outputType) double convert(String coordinate) Coordinates(double latitude. location Object ➥Landmark AddressInfo getAddressInfo() String getDescription() String getName() QualifiedCoordinates getQualifiedCoordinates() ❉ Landmark(String name.Almanac double getLatitude() double getLongitude() void setAltitude(float altitude) void setLatitude(double latitude) void setLongitude(double longitude) Criteria javax.location Object ➥Criteria ❉ Criteria() int getHorizontalAccuracy() int getPreferredPowerConsumption() int getPreferredResponseTime() int getVerticalAccuracy() boolean isAddressInfoRequired() boolean isAllowedToCost() boolean isAltitudeRequired() boolean isSpeedAndCourseRequired() ✍■ ✍■ ✍■ ✍■ int NO_REQUIREMENT int POWER_USAGE_HIGH int POWER_USAGE_LOW int POWER_USAGE_MEDIUM void setAddressInfoRequired(boolean addressInfoRequired) void setAltitudeRequired(boolean altitudeRequired) void setCostAllowed(boolean costAllowed) void setHorizontalAccuracy(int accuracy) void setPreferredPowerConsumption(int level) void setPreferredResponseTime(int time) void setSpeedAndCourseRequired(boolean speedAndCourseRequired) void setVerticalAccuracy(int accuracy) Landmark javax.microedition. QualifiedCoordinates coordinates. String description.microedition. AddressInfo addressInfo) void setAddressInfo(AddressInfo addressInfo) void setDescription(String description) void setName(String name) void setQualifiedCoordinates(QualifiedCoordinates coordinates) 74 . LandmarkException java. String category) throws java.io.IOException java.util. double maxLatitude.Enumeration getLandmarks(String category.Enumeration getLandmarks() throws java.IOException ❏ ❏ ❏ void createLandmarkStore(String storeName) throws java.io.microedition.io. java.io. String name) throws java.util.IOException. double minLatitude.location Object ➥LandmarkStore void addCategory(String categoryName) throws LandmarkException.io.Enumeration getLandmarks(String category.io. double minLongitude.location Object ➥Throwable ➥Exception ➥LandmarkException ❉ ❉ LandmarkException() LandmarkException(String s) LandmarkStore javax.util.IOException void addLandmark(Landmark landmark.io. LandmarkException Location javax.IOException String[] listLandmarkStores() throws java.location Object ➥Location AddressInfo getAddressInfo() float getCourse() String getExtraInfo(String mimetype) int getLocationMethod() QualifiedCoordinates getQualifiedCoordinates() float getSpeed() long getTimestamp() boolean isValid() ❉♦ Location() 75 .io.microedition.util.io.IOException void updateLandmark(Landmark lm) throws java.IOException.IOException.IOException. double maxLongitude) throws java.io.IOException ❏ java.Enumeration getCategories() LandmarkStore getInstance(String storeName) java.IOException void deleteLandmark(Landmark lm) throws java.io. LandmarkException void deleteCategory(String categoryName) throws LandmarkException.microedition. String category) throws java. LandmarkException void deleteLandmarkStore(String storeName) throws java. java.Almanac LandmarkException javax.IOException void removeLandmarkFromCategory(Landmark lm.io. int newState) LocationProvider Object ➥LocationProvider ❏ ✍■ ❏ ❏ ❍ ❍ ❉♦ ✍■ ❏ ❍ ❍ ✍■ 76 javax.microedition. int timeout.location LocationListener void locationUpdated(LocationProvider provider.microedition.location void addProximityListener(ProximityListener listener. Coordinates coordinates. InterruptedException int getState() LocationProvider() int OUT_OF_SERVICE void removeProximityListener(ProximityListener listener) void reset() void setLocationListener(LocationListener listener. int interval. Location location) void providerStateChanged(LocationProvider provider.location Object ➥Throwable ➥Exception ➥LocationException ❉ ❉ LocationException() LocationException(String s) LocationListener javax. float proximityRadius) throws LocationException int AVAILABLE LocationProvider getInstance(Criteria criteria) throws LocationException Location getLastKnownLocation() Location getLocation(int timeout) throws LocationException.Almanac ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ ✍■ int MTA_ASSISTED int MTA_UNASSISTED int MTE_ANGLEOFARRIVAL int MTE_CELLID int MTE_SATELLITE int MTE_SHORTRANGE int MTE_TIMEDIFFERENCE int MTE_TIMEOFARRIVAL int MTY_NETWORKBASED int MTY_TERMINALBASED LocationException javax.microedition. int maxAge) int TEMPORARILY_UNAVAILABLE . location Object ➥Coordinates ➥QualifiedCoordinates float getHorizontalAccuracy() float getVerticalAccuracy() ❉ QualifiedCoordinates(double latitude.location ProximityListener void monitoringStateChanged(boolean isMonitoringActive) void proximityEvent(Coordinates coordinates. float verticalAccuracy) void setHorizontalAccuracy(float horizontalAccuracy) void setVerticalAccuracy(float verticalAccuracy) 77 .microedition. float altitude. float roll) ProximityListener javax. float pitch.microedition. double longitude. Location location) QualifiedCoordinates javax.Almanac Orientation javax. boolean isMagnetic. float horizontalAccuracy.location Object ➥Orientation float getCompassAzimuth() ❏ Orientation getOrientation() throws LocationException float getPitch() float getRoll() boolean isOrientationMagnetic() ❉ Orientation(float azimuth.microedition. Almanac 78 . location.microedition.AddressInfo 14 AVAILABLE of javax.microedition.microedition.AddressInfo 12 createLandmarkStore(String) of javax.LandmarkStore 37 addProximityListener(ProximityListener.location 22 Criteria() of javax.location.microedition.location.Coordinates 17 deleteCategory(String) of javax.AddressInfo 13 C E CITY of javax.AddressInfo 12 EXTENSION of javax.location.microedition.microedition.location.AddressInfo 13 D BUILDING_FLOOR of javax.microedition.microedition.Coordinates 18 Coordinates of javax.location.LandmarkStore 38 deleteLandmarkStore(String) of javax.microedition.location.LandmarkStore 38 deleteLandmark(Landmark) of javax.location.microedition.location.LandmarkStore 39 79 .microedition.location.location.microedition.location. Coordinates.microedition.LandmarkStore 36 addLandmark(Landmark.AddressInfo 12 COUNTY of javax.Coordinates 18 convert(String) of javax.microedition.microedition.microedition.microedition.location.microedition.location 10 AddressInfo() of javax.Coordinates 17 COUNTRY of javax.LocationProvider 54 azimuthTo(Coordinates) of javax.location.Criteria 24 CROSSING1 of javax.Coordinates 19 DISTRICT of javax.Landmark 30 of javax.microedition.location.microedition.microedition.microedition.microedition.location.microedition.location.location.microedition.microedition. double.Location 46 getAltitude() of javax.Coordinates 20 getCategories() of javax.location.AddressInfo 13 B G getAddressInfo() of javax.microedition.location. String) of javax.location.location.microedition.location.microedition.location. int) of javax.AddressInfo 12 DD_MM of javax.location 16 Coordinates(double.microedition. float) of javax.LocationProvider 55 AddressInfo of javax.microedition.AddressInfo 12 BUILDING_ROOM of javax.Index A addCategory(String) of javax.location.location.AddressInfo 12 convert(double.location.location.microedition.microedition.LandmarkStore 37 Criteria of javax.location.location.AddressInfo 12 BUILDING_ZONE of javax.microedition.AddressInfo 11 BUILDING_NAME of javax.microedition.location.microedition.Coordinates 17 DD_MM_SS of javax.location.Coordinates 18 COUNTRY_CODE of javax.AddressInfo 13 CROSSING2 of javax.LandmarkStore 39 distance(Coordinates) of javax. float) of javax.location. Criteria 25 getQualifiedCoordinates() of javax.applet .microedition.microedition.location.LocationProvider 57 getTimestamp() of javax. double.microedition.location.Orientation 61 getCourse() of javax.microedition.location. String.microedition.location. String) of javax.location.Criteria 25 isAllowedToCost() of javax.Orientation 62 getSpeed() of javax.LandmarkException 33 .microedition.location.Criteria 24 80 getPreferredResponseTime() of javax.location.LandmarkStore 39 getLandmarks() of javax.location.location.location.location.Location 46 getDescription() of javax.location.Location 47 getLongitude() of javax.microedition.LandmarkStore 40 getLandmarks(String.microedition.QualifiedCoordinates 66 I isAddressInfoRequired() of javax.LandmarkStore 40 getLandmarks(String.location. QualifiedCoordinates.location.location.LandmarkStore 41 getLastKnownLocation() of javax. double) of javax.microedition.location.microedition.microedition.location. AddressInfo) of javax.microedition.location 29 Landmark(String.location.LocationProvider 55 getInstance(String) of javax.LocationProvider 56 getLatitude() of javax.microedition.Location 48 getState() of javax.location.microedition.Landmark 31 of javax.location.Criteria 25 isAltitudeRequired() of javax.package 71 L Landmark of javax.location.Criteria 26 isValid() of javax.microedition.location.Landmark 30 LandmarkException of javax.microedition.location.microedition.Location 48 getRoll() of javax.location. double.microedition.microedition.location.location.Index getCompassAzimuth() of javax.microedition.AddressInfo 14 getHorizontalAccuracy() of javax.location.Orientation 61 getPitch() of javax.microedition.microedition.location.location.microedition.Criteria 25 of javax.microedition.QualifiedCoordinates 66 getInstance(Criteria) of javax.location.microedition.Coordinates 20 getName() of javax.microedition.location.microedition.Criteria 24 of javax.microedition.location.microedition.Orientation 62 getPreferredPowerConsumption() of javax.Landmark 30 getExtraInfo(String) of javax.LocationProvider 57 getLocationMethod() of javax.microedition.microedition.location.location.Coordinates 20 getLocation(int) of javax.location.microedition.microedition.microedition.microedition.location 33 LandmarkException() of javax.microedition.Location 46 getField(int) of javax.microedition.microedition.Criteria 25 isOrientationMagnetic() of javax.microedition. double.Orientation 62 isSpeedAndCourseRequired() of javax.location.Landmark 30 getOrientation() of javax.location.microedition.Location 48 getVerticalAccuracy() of javax.Location 48 J java.location. microedition.location.location.microedition. float) of javax.location 51 LocationProvider of javax.location.Location 45 MTE_TIMEDIFFERENCE of javax.microedition.ProximityListener 64 ProximityListener of javax.microedition.location.location. float.microedition.microedition. float) of javax.microedition.microedition.Location 46 N NO_REQUIREMENT of javax.location.LocationListener 51 M monitoringStateChanged(boolean) of javax.location 49 LocationException() of javax.location 35 listLandmarkStores() of javax.location 65 QualifiedCoordinates(double.LocationListener 52 proximityEvent(Coordinates.Location 46 LocationException of javax.microedition.location.microedition. Location) of javax.LocationException 50 LocationListener of javax.location.LandmarkException 33 LandmarkStore of javax.location. int) of javax.location.location.Location 45 MTY_NETWORKBASED of javax.location. float.location.Criteria 24 providerStateChanged(LocationProvider.location.location.location 63 Q QualifiedCoordinates of javax.Location 45 MTE_SATELLITE of javax.AddressInfo 13 POSTAL_CODE of javax.location.location.microedition.Criteria 24 POWER_USAGE_LOW of javax.microedition.QualifiedCoordinates 66 81 .location.microedition.microedition. Location) of javax.location 43 Location() of javax.microedition.microedition.location.location.microedition.location.location 60 Orientation(float. double.location.microedition.microedition.location.location.Location 45 MTE_SHORTRANGE of javax.location.AddressInfo 13 POWER_USAGE_HIGH of javax.microedition.Criteria 23 O Orientation of javax.location.microedition. float.microedition.Location 45 MTY_TERMINALBASED of javax. boolean.Index LandmarkException(String) of javax.LocationException 49 LocationException(String) of javax.microedition.microedition.Location 44 MTE_CELLID of javax.microedition.LocationProvider 54 locationUpdated(LocationProvider.ProximityListener 63 MTA_ASSISTED of javax.Location 44 MTA_UNASSISTED of javax.microedition.microedition.Location 45 MTE_TIMEOFARRIVAL of javax.LandmarkStore 41 Location of javax.LocationProvider 54 P PHONE_NUMBER of javax.location 53 LocationProvider() of javax.microedition.microedition.location.microedition.location.location.Location 44 MTE_ANGLEOFARRIVAL of javax.microedition.microedition.Criteria 24 POWER_USAGE_MEDIUM of javax.microedition.microedition.microedition.microedition.Orientation 61 OUT_OF_SERVICE of javax.microedition. microedition.LocationProvider 58 S setAddressInfo(AddressInfo) of javax.microedition.location.location.LandmarkStore 42 URL of javax.Landmark 32 82 setSpeedAndCourseRequired(boolean) of javax.microedition.LocationProvider 57 reset() of javax.microedition.microedition.location.microedition.microedition.location.microedition.location. String) of javax.Criteria 27 setLatitude(double) of javax.microedition.microedition.microedition. int) of javax.Criteria 26 setDescription(String) of javax.location.AddressInfo 14 .location.microedition.AddressInfo 14 T TEMPORARILY_UNAVAILABLE of javax.location.LandmarkStore 41 removeProximityListener(ProximityListener) of javax.LocationProvider 54 U updateLandmark(Landmark) of javax.microedition.AddressInfo 14 setHorizontalAccuracy(float) of javax. String) of javax.microedition.location.Landmark 31 setField(int.location.location.Criteria 26 setAltitude(float) of javax.Coordinates 20 setAltitudeRequired(boolean) of javax.microedition.location.Landmark 31 setAddressInfoRequired(boolean) of javax.location.location.Index R removeLandmarkFromCategory(Landmark.microedition.LocationProvider 58 setLongitude(double) of javax.Criteria 26 setCostAllowed(boolean) of javax.Coordinates 21 setLocationListener(LocationListener.AddressInfo 13 STREET of javax.location.microedition.location.location.location.Criteria 28 setVerticalAccuracy(float) of javax.microedition. int.location.location.microedition.QualifiedCoordinates 67 setHorizontalAccuracy(int) of javax.location.microedition.Coordinates 21 setName(String) of javax.microedition.microedition.microedition.Criteria 28 STATE of javax.microedition.Landmark 31 setPreferredPowerConsumption(int) of javax.Criteria 27 setPreferredResponseTime(int) of javax.microedition.microedition.location.Criteria 27 setQualifiedCoordinates(QualifiedCoordinates) of javax.location.location.location.microedition.location.QualifiedCoordinates 67 setVerticalAccuracy(int) of javax. int.location.