These days the talks of location based services are very hot in the industry. In fact even outside the mobile telephony industry even advertisers are watching the technical developments in the space of mobile based location services very curiously. Location based services arouse so much interest because they will fundamentally change the utility curve of the mobile phone and PDAs for good.

Just think what impact will these services will have on the pizza chains, the traffic sites, the supply chain management companies and the media and you will begin to grasp the value these services will be adding to the daily lives of people. Imagine an application that lets you choose the pizza from a predefined menu and orders the closest pizza corner. Imagine the savings and control the supply chain management companies will be able to achieve by using location based mobile services. It was sensing this impending revolution that the founders of J2ME came out with the Location API contained in the JSR 179.

These application programming interfaces (APIs) give you incredible flexibililty and power to develop location services based applications. This API helps us programmers to obtain the following information:

·   Current geographic position

·   Orientation of the terminal

·   Accesing the database of landmarks stored in the terminal

This API is in form of an optional package that could be added by handset manufacturers to the device based on there desire. The minimum version of CLDC needed to run this API is CLDC 1.1. This optional package could also be added on top of the Connected Device Configuration (CDC).

javax.microedition.location

 

public class AddressInfo

What is it?

This class contains the textual address information about a location. The information may include information like street name, postal code, city etc. This class defines field constants that can be used to retrieve specific field data.

o    Constructor

·         public AddressInfo()

This constructor constructs the AddressInfo object will all field values set to null.

o    Fields

·         public static final int BUILDING_FLOOR

This address field denotes a building floor.

·         public static final int BUILDING_NAME

This address field denotes a building name.

·         public static final int BUILDING_ROOM

This address field denotes a building room.

·         public static final int BUILDING_ZONE

This address field denotes a building zone

·         public static final int CITY

This address field denotes town or city name.

·         public static final int COUNTRY

This address field denotes a country.

·         public static final int COUNTRY_CODE

This address field denotes a country as a two-letter ISO 3166-1 code.

·         public static final int COUNTY

This address field denotes a county. A county is an entity between a state and a city.

·         public static final int CROSSING1

This address field denotes a street in a crossing.

·         public static final int CROSSING2

This address field denotes a street in a crossing.

·         public static final int DISTRICT

This address field denotes a municipal district.

·         public static final int EXTENSION

This address field denotes an address extension, e.g. house number.

·         public static final int PHONE_NUMBER

This address field denotes a phone number for this place.

·         public static final int POSTAL_CODE

This address field denotes a postal code.

·         public static final int STATE

This address field denotes a state or province.

·         public static final int STREET

This address field denotes a street name and number.

·         public static final int URL

This address field denotes a URL for this place.

o    Methods

·         public String getField(int field)

This method returns the address field string. If the specified field is not set this method will return null value.

·         public void setField(int field, String value)

This method sets the value of an address field. 

public class Coordinates

What is it?

This class represents location coordinates as latitude-longitude-altitude values. The latitude and longitude values are represented as decimal degree values. The decimal values are in form of float values. It also provides convenience methods for converting between string coordinate representation and the double representation used in this class.

o    Constructor

• public Coordinates(double latitude, double longitude, float altitude)

This constructor constructs a new Coordinates object with the given values. The following is the description of the parameters which this constructor accepts:

o    latitude - the latitude of the location.

Valid range: [-90.0, 90.0]. Northern latitudes are represented by positive values while southern latitudes are represented by negative values.

o    longitude - the longitude of the location.

Valid range: [-180.0, 180.0). Eastern longitudes are represented by positive values and western longitudes are represented by negative values.

o    altitude - the altitude of the location in meters. It is defined as height above the WGS84 ellipsoid. The Float.NaN value indicates that the altitude is not known.

o    Fields

·         public static final int DD_MM

This field is an identifier for string coordinate representation Degrees, Minutes, decimal fractions of a minute.

·         public static final int DD_MM_SS

This field is an identifier for string coordinate representation Degrees, Minutes, Seconds and decimal fractions of a second.

o    Methods

·         public float azimuthTo(Coordinates to)

This method returns the azimuth to the destination in degrees. The result shall be within the range [0.0, 360.0].

·         public static java.lang.String convert(double coordinate, int outputType)

This method converts a double representation of a coordinate with decimal degrees into a string representation.

·         public static double convert(String coordinate)

This method converts a String representation of a coordinate into the double representation.

·         public float distance(Coordinates to)

This method calculates the geodetic distance between the two points according to the ellipsoid model of WGS84. The altitude is neglected from calculations. This method returns the distance to the destination in meters.

·         public float getAltitude()

This method returns the altitude in meters above the reference ellipsoid for this location coordinate.

·         public double getLatitude()

This method returns the latitude in degrees.

·         public double getLongitude()

This method returns the longitude in degrees.

·         public void setAltitude(float altitude)

This method sets the geodetic altitude for this point.

·         public void setLatitude(double latitude)

This method sets the geodetic latitude for this point.

·         public void setLongitude(double longitude)

This method sets the geodetic longitude for this point.

public class Criteria

What is it?

This class is of prime importance in selecting of the location provider.

o    Constructor

·         public Criteria()

This method constructs a Criteria object.

o    Fields

·         public static final  int NO_REQUIREMENT

This field stands for a constant indicating no requirements for the parameter.

·         public static final int POWER_USAGE_HIGH

This field stands for a level indicating high power consumption allowed.

·         public static final int POWER_USAGE_LOW

This field stands for a level indicating only low power consumption allowed.

·         public static final int POWER_USAGE_MEDIUM

This field stands for a level indicating average power consumption allowed.

o    Methods

·         public int getHorizontalAccuracy()

This method returns the horizontal accuracy in meters

·         public int getPreferredPowerConsumption()

This method returns the preffered power consumption level.

·         public int getPreferredResponseTime()

This method returns the preffered maximum response time in milliseconds.

·         public int getVerticalAccuracy()

This method returns the vertical accuracy value set in this Criteria.

·         public boolean isAddressInfoRequired()

This method returns whether the location provider should be able to normally provide textual address information. The returned value true means that it should be able to do so. A return value of false means that AddressInfo is not required.

·         public boolean isAllowedToCost()

This method returns the preferred cost setting. The returned value true means it is allowed to cost. A return value false means it must be free of charge.

·         public boolean isAltitudeRequired()

This method returns whether the location provider should be able to determine altitude. The value true means that it should be able to return the altitude information. The value false means that the ability to return the altitude information is not required.

·         public boolean isSpeedAndCourseRequired()

This method returns whether the location provider should be able to determine speed and course. True means that it should be able to do so. False means that this is not required doing so.

·         public void setAddressInfoRequired(boolean addressInfoRequired)

This method sets whether the location provider should be able to determine textual address information or not.

·         public void setAltitudeRequired(boolean altitudeRequired)

This method sets whether the location provider should be able to determine altitude. The default value is false.

·         public void setCostAllowed(boolean costAllowed)

This method sets whether the requests for location determination is allowed to incur any financial cost to the user of the terminal or not.

·         public void setHorizontalAccuracy(int accuracy)

This method sets the desired horizontal accuracy preference. The horizontal accuracy is given in meters.

·         public void setPreferredPowerConsumption(int level)

This method sets the preferred maximum level of power consumption.

·         public void setPreferredResponseTime(int time)

This method sets the desired maximum response time preference.

·         public void setSpeedAndCourseRequired(boolean speedAndCourseRequired)

This method sets whether the location provider should be able to determine speed and course. The default value is false.

·         public void setVerticalAccuracy(int accuracy)

This method sets the desired vertical accuracy preference. The vertical accuracy is given in meters.  

public class Landmark

What is it?

The Landmark class represents a landmark, i.e. a known location with a name. This class is only a container for the information on a landmark.

o    Constructor

·         public Landmark(String name, String description, QualifiedCoordinates coordinates, AddressInfo addressInfo)

This constructor constructs a new landmark object with the given parameters. The following are descriptions of parameters this constructor takes:

·         name - The name of the landmark

·         description – The description of the landmark. It may be null if not available.

·         coordinates - The Coordinates of the landmark. It may be null if not known.

·         addressInfo - The textual address information of the landmark. It may be null if not known.

o    Methods

·         public AddressInfo getAddressInfo()

This method returns the AddressInfo of the landmark

·         public String getDescription()

This method returns returns the description of the landmark. It may return a null if no description is available.

·         public String getName()

This method returns the name of the landmark

·         public QualifiedCoordinates getQualifiedCoordinates()

This method returns the QualifiedCoordinates of the landmark. It may return null if they are not available.

·         public void setAddressInfo(AddressInfo addressInfo)

This method sets the AddressInfo of the landmark.

·         public void setDescription(String description)

This method sets the description of the landmark.

·         public void setName(String name)

This method sets the name of the landmark.

·         public void setQualifiedCoordinates(QualifiedCoordinates coordinates)

This method sets the QualifiedCoordinates of the landmark.

public class LandmarkStore

What is it?

This class provides methods to store, delete and retrieve landmarks from a persistent landmark store.

o    Method

·         public void addCategory(String categoryName)

This method adds a category to this LandmarkStore.

·         public void addLandmark(Landmark landmark, String category)

This method adds a landmark to the specified group in the landmark store.

·         public static void createLandmarkStore(String storeName)

This method creates a new landmark store with a specified name.

·         public void deleteCategory(String categoryName)

This method removes a category from this LandmarkStore.

·         public void deleteLandmark(Landmark lm)

This method deletes a landmark from this LandmarkStore.

·         public void deleteLandmarkStore(String storeName)

This method deletes a landmark store with a specified name.

·         public Enumeration getCategories()

This method returns a java.util.Enumeration containing Strings representing the category names. In case there are no categories defined in this LandmarkStore, an Enumeration with no entries is returned.

·         public static LandmarkStore getInstance(String storeName)

This method returns the LandmarkStore object representing the specified landmark store. It will return null if a landmark store with the specified name does not exist.

·         public Enumeration getLandmarks()

This method returns an Enumaration that lists all landmarks stored in the store.

·         public Enumeration getLandmarks(String category, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude)

This method returns an Enumaration that lists all the landmarks that are within an area defined by bounding minimum and maximum latitude and longitude and belong to the defined category in case it is specified.

·         public Enumeration getLandmarks(String category, String name)

This method returns an Enumeration containing all the matching Landmarks. It may return null if no Landmark matched the given parameters.

·         public static String[] listLandmarkStores()

This method returns an array of landmark store names.

·         public void removeLandmarkFromCategory(Landmark lm, String category)

This method removes the named landmark from the specified category.

·         public void updateLandmark(Landmark lm)

This method updates the information about a landmark.

public class Location

What is it?

This class represents the standard set of basic location information. This includes the information relating to the following:

·         Timestamped coordinates

·         Accuracy

·         Speed

·         Course

·         Information about the positioning method used for the location

·         Optional textual address

o    Field

·         public static final int MTA_ASSISTED

This field tells that the location method is assisted by the other party

·         public static final int MTA_UNASSISTED

This field tells that the location method is unassisted.

·         public static final int MTE_ANGLEOFARRIVAL

This field defines the location method technology: Angle of Arrival for cellular.

·         public static final int MTE_CELLID

This field defines the location method technology: Cell-ID for cellular.

·         public static final int MTE_SATELLITE

This field defines the location method technology: satellites.

·         public static final int MTE_SHORTRANGE

This field defines the location method technology: Short-range positioning system.

·         public static final int MTE_TIMEDIFFERENCE

This field defines the location method technology: Time Difference for cellular / terrestrial RF system

·         public static final int MTE_TIMEOFARRIVAL

This field defines the location method technology: Time of Arrival (TOA) for cellular / terrestrial RF system.

·         public static final int MTY_NETWORKBASED

This field tells that the location method is of type network based.

·         public static final int MTY_TERMINALBASED

This field tells that the location method is of type terminal based.

o    Methods

·         public AddressInfo getAddressInfo()

This method returns an AddressInfo associated with this Location object.

·         public float getCourse()

This method returns the terminal’s course made good in degrees relative to true north or Float.NaN if the course is not known.

·         public String getExtraInfo(String mimetype)

This method returns string encoded according to the format identified by the MIME type defined in the parameter.

·         public int getLocationMethod()

This method returns a bit field identifying the used location method.

·         public QualifiedCoordinates getQualifiedCoordinates()

This method returns a QualifiedCoordinates object. If the coordinates are not known it returns null.

·         public float getSpeed()

This method returns the current ground speed in m/s for the terminal or Float.NaN if the speed is not known.

·         public long getTimestamp()

This method returns a timestamp representing the time.

·         public boolean isValid()

This method returns a boolean value with true indicating that this Location instance is valid and false indicating an invalid Location instance. 

public interface LocationListener

What is it?

This interface represents a listener that receives events associated with a particular LocationProvider. Generally the device shall attempt to provide the application with position information at regular intervals. But the frequency of this information can not be guaranteed due to various factors.

o    Methods

·         public void locationUpdated(javax.microedition.location.LocationProvider provider, javax.microedition.location.Location location)

This method is called, by the LocationProvider to which this listener is registered, periodically according to the interval defined when registering the listener to provide updates of the current location.

·         public void providerStateChanged(javax.microedition.location.LocationProvider provider, int newState)

This method is called by the LocationProvider to which this listener is registered if the state of the LocationProvider has changed.

public abstract class LocationProvider

What is it?

This is one of the most important classes of Location API. It represents a location-providing module which generates locations. You can use an instance of this class by using the factory method getInstance which is explained below.

o    Fields

·         public static final int AVAILABLE

This field may be returned by the getState method. This field tells that the location provider is available.

·         public static int final OUT_OF_SERVICE

This field may be returned by the getState method. This field tells that the location provider is out of service. This field means that the provider is unavailable and the implementation is not able to expect that this situation would change in the near future.

·         public static final int TEMPORARILY_UNAVAILABLE

This field may be returned by the getState method. This field tells that the location provider is temporarily unavailable. This field 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.

o    Methods

·         public static void addProximityListener(ProximityListener listener, Coordinates coordinates, float proximityRadius)

This method is used for adding a ProximityListener for receiving updates when proximity to the specified coordinates is detected.

·         public static LocationProvider getInstance(Criteria criteria)

This factory method is used to get an actual LocationProvider implementation based on the defined criteria. This is the factory method that is used for getting an instance of this class. This method will throw the LocationException if all supported location providers are out service. If this method returns null then it means that there are location providers in the system that were not returned because the criteria did not match.

·         public static Location getLastKnownLocation()

This method returns a location object. A null value is returned if the system does not have any previous location information.

·         public abstract Location getLocation(int timeout)

This method returns a Location object.

·         public abstract int getState()

This method returns the availability status of this LocationProvider.

·         public static void removeProximityListener(ProximityListener listener)

This method removes a ProximityListener from the list of recipients for updates.

·         public abstract void reset()

This method resets the LocationProvider.

·         public abstract void setLocationListener(LocationListener listener, int interval, int timeout, int maxAge)

This method adds a LocationListener for receiving updates at the defined interval.

public class Orientation

What is it?

This class represents the physical orientation of the terminal. It is described by the following:

·   Azimuth to north (the horizontal pointing direction)

·   Pitch (the vertical elevation angle)

·   Roll (the rotation of the terminal around its own longitudinal axis)

This class is only a container for the information.

o        Constructor

·         public Orientation(float azimuth, boolean isMagnetic, float pitch, float roll)

This constructor constructs a new Orientation object with the given parameters. It does not validate the values while accepting them. The values are expressed in degrees represented in form of float values.

o        Methods

·         public float getCompassAzimuth()

This method returns the terminal’s compass azimuth in degrees relative to true or magnetic north.

·         public static Orientation getOrientation()

This method returns returns an Orientation object containing the terminal’s current orientation or it returns null if the orientation can’t be currently determined.

·         public float getPitch()

This method returns the terminal’s pitch in degrees or Float.NaN if it is not available.

·         public float getRoll()

This method returns the terminal’s roll in degrees or Float.NaN if it is not available.

·         public boolean isOrientationMagnetic()

This method returns true if this Orientation is relative to the magnetic field of the Earth. Otherwise it returns false if this Orientation is relative to true north and gravity.

public interface ProximityListener

What is it?

ProximityListener interface is used as a listener for events associated with detecting proximity to some registered coordinates. It is called when the terminal enters the proximity of the registered coordinates. It is called only once when the terminal enters the proximity of the registered coordinates. Thus applications which need to listen to this sort of events regularly must re-register.

o    Methods

·         public void monitoringStateChanged(boolean isMonitoringActive)

This method is called to notify that the state of the proximity monitoring has changed.

·         public void proximityEvent(Coordinates coordinates, Location location)

This method will be called by the platform when it is detected that the current location of the terminal is within the defined proximity radius of the registered coordinates.

public class QualifiedCoordinates

What is it?

This class represents coordinates as latitude-longitude-altitude values that are associated with an accuracy value.

o    Constructor

·         public QualifiedCoordinates(double latitude, double longitude, float altitude, float horizontalAccuracy, float verticalAccuracy)

This constructor constructs a new object of this class with values in the parameters.

o    Methods

·         public float getHorizontalAccuracy()

This method returns the horizontal accuracy in meters. It may also return Float.NaN if this is not known.

·         public float getVerticalAccuracy()

This method returns the vertical accuracy in meters. It may also return Float.NaN if this is not known.

·         public void setHorizontalAccuracy(float horizontalAccuracy)

This method sets the horizontal accuracy of the location in meters.

·         public void setVerticalAccuracy(float verticalAccuracy)

This method sets the vertical accuracy of the location in meters.

public class LocationException

What is it?

This exception is thrown when a location API specific error occurrs.

o    Constructor

·         public LocationException()

·         public LocationException(String s) 

public class LandmarkException

What is it?

This exception is thrown when an error related to handling landmarks has occurred.

o    Constructor

·         public LandmarkException()

public LandmarkException(String s)