javax.microedition.location
Class Landmark

java.lang.Object
  javax.microedition.location.Landmark

public class Landmark
extends java.lang.Object

The Landmark class represents a landmark, such as a known location with a name. A landmark has a name by which it is known to the end user, a textual description, QualifiedCoordinates, AddressInfo, timestamp of the last change, identifier, covered GeographicArea, author and possible additional information and URLs to additional content.

This class is only a container for the information, it preserves the references to the objects. The constructor does not validate the parameters passed in but just stores the values, except the name field is never allowed to be null. The get* methods return the values passed in the constructor or if the values are later modified by calling the set* methods, the get* methods return the modified values. The QualifiedCoordinates, AddressInfo objects inside the landmark is a mutable object and the Landmark object holds only a reference to it. A landmark also contains immutable information, like the GeographicArea. It is possible to modify the QualifiedCoordinates object inside the Landmark object by calling the set* methods in the QualifiedCoordinates object. However, any such dynamic modifications affect only the Landmark object instance, but must not automatically update the persistent landmark information in the landmark store. The LandmarkStore.updateLandmark method is the only way to commit the modifications to the persistent landmark store. So if an application changes the QualifiedCoordinates of the landmark and wants to store those changes, it must explicitly call LandmarkStore.updateLandmark() method.

When the platform implementation returns Landmark objects, it must ensure that it only returns objects where the parameters have values set as described for their semantics in this class.

In version 2.0 of the Location API, new fields are added to the landmark. These fields are identifier, author, extraInfo, geographicArea, urls and timestamp. The identifier and author combination is unique inside a landmark store and allows the application developers refer to specified landmarks even though the name of the landmark has changed. The author indicates the provider or developer of the landmark and it should be a reverse domain name. The coverage area of the landmark is specified with the geographicArea field. It may be any of the shape specific subclasses of GeographicArea class. The timestamp field is added to better track when the data in a landmark has been changed. The urls field may contain links to additional content attached to the landmark. With the extraInfo field the application developer is able to provide additional information about the landmark. This information can be, for example, speed or heading of the landmark.

Field Summary

static int

NO_IDENTIFIER Constant for indicating that the identifier is not defined.

Constructor Summary

Landmark(java.lang.String name, java.lang.String description, QualifiedCoordinates coordinates, AddressInfo addressInfo)
Constructs a new Landmark object with the values specified.

Landmark(java.lang.String name, java.lang.String description, QualifiedCoordinates coordinates, AddressInfo addressInfo, int identifier, GeographicArea area, java.lang.String author, java.lang.String[][] urls, java.lang.String[] extraInfo)
Constructs a new Landmark object with the values specified.

Method Summary

boolean	equals(java.lang.Object landmark) Overriding the equals method in Object class to compare the equality of values in two Landmark objects.
AddressInfo	getAddressInfo() Gets the AddressInfo of the landmark.
java.lang.String	getAuthor() Returns the author of the landmark.
java.lang.String[]	getCategories() Returns the categories this landmark instance is currently added at the time this landmark instance was created.
java.lang.String	getDescription() Gets the landmark description.
java.lang.String[]	getExtraInfo() Returns the extra information of the landmark.
GeographicArea	getGeographicArea() Returns the coverage area of the landmark.
int	getIdentifier() Returns the identifier of the landmark.
java.lang.String	getLandmarkStoreName() Returns the name of the landmark store this landmark instance currently belongs to at the time this landmark instance was created.
java.lang.String	getName() Gets the landmark name.
QualifiedCoordinates	getQualifiedCoordinates() Gets the QualifiedCoordinates of the landmark.
long	getTimestamp() Gets the timestamp of the landmark.
java.lang.String[][]	getURL() Returns the two-dimensional array that contains the URLs and descriptions for them set for the landmark.
int	hashCode() Overriding the hashCode method in Object class.
void	setAddressInfo(AddressInfo addressInfo) Sets the AddressInfo of the landmark.
void	setAuthor(java.lang.String author) Sets the author or the provider of the landmark data, may be null.
void	setDescription(java.lang.String description) Sets the description of the landmark.
void	setExtraInfo(java.lang.String[] extraInfo) Sets the additional information to the landmark.
void	setGeographicArea(GeographicArea area) Sets the coverage area for the landmark.
void	setIdentifier(int identifier) Sets the identifier of the landmark.
void	setName(java.lang.String name) Sets the name of the landmark.
void	setQualifiedCoordinates(QualifiedCoordinates coordinates) Sets the QualifiedCoordinates of the landmark.
void	setURL(java.lang.String[][] urls) Sets the URLs and their descriptions for a landmark.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_IDENTIFIER

public static final int NO_IDENTIFIER

Constant for indicating that the identifier is not defined.

Since:

2.0

See Also:

Constant Field Values

Constructor Detail

Landmark

public Landmark(java.lang.String name,
                java.lang.String description,
                QualifiedCoordinates coordinates,
                AddressInfo addressInfo)

Constructs a new Landmark object with the values specified. Using this constructor defined already in version 1.0 sets the fields added in version 2.0 to default values. This means that author, coverage area, extra info and URLs are set to null and identifier to NO_IDENTIFIER.

Parameters:

name - the name of the landmark

description - description of the landmark, may be null if not available

coordinates - the Coordinates of the landmark, may be null if not known

addressInfo - the textual address information of the landmark, may be null if not known

Throws:

java.lang.NullPointerException - if the name is null

Landmark

public Landmark(java.lang.String name,
                java.lang.String description,
                QualifiedCoordinates coordinates,
                AddressInfo addressInfo,
                int identifier,
                GeographicArea area,
                java.lang.String author,
                java.lang.String[][] urls,
                java.lang.String[] extraInfo)

Constructs a new Landmark object with the values specified. identifier is the unique identifier of the landmark within the landmarks from same author. NO_IDENTIFIER can be used as the identifier to indicate it is not set. The extraInfo is a String array of additional information items. Passing null or an empty array as extraInfo indicates no additional information is available. The additional information may be application specific and not necessarily visible to the user. The urls parameter contains URLs and descriptions for the landmark. They are given as a two-dimensional array that is handled as an array inside an array. It means that one URL and description pair is stored in an array, where URL has the index 0 and the description is in index 1. These pair arrays are stores in another array. If the URL in the pair is an empty array, an IllegalArgumentException is thrown. If the URL does not have a description an empty String must be used. Passing null or an empty array as urls parameter indicates no URL and description information is available.

Parameters:

name - the name of the landmark

description - description of the landmark, may be null if not available

coordinates - the Coordinates of the landmark, may be null if not known

addressInfo - the textual address information of the landmark, may be null if not known

identifier - the identifier of the landmark

area - the coverage area of the landmark, may be null

author - the provider of the landmark data, may be null

urls - an array of URLs and descriptions for the landmark, where the first elements in the pair contains the URL and the second element the corresponding description, may be null or an empty array

extraInfo - an array of additional information about the landmark, may be null or an empty array

Throws:

java.lang.IllegalArgumentException - if identifier < -1 (=NO_IDENTIFIER) or identifier = 0 or the number of elements in the inner array in the urls parameter is not 2 or if any URL element in the inner array of urls parameter is an empty String

java.lang.NullPointerException - if the name is null or if urls or extraInfo contains null elements

Since:

2.0

Method Detail

getName

public java.lang.String getName()

Gets the landmark name.

Returns:

the name of the landmark

See Also:

setName(String)

getDescription

public java.lang.String getDescription()

Gets the landmark description.

Returns:

the description of the landmark, null if not available

See Also:

setDescription(String)

getQualifiedCoordinates

public QualifiedCoordinates getQualifiedCoordinates()

Gets the QualifiedCoordinates of the landmark.

If a coverage area has been set for this landmark but the coordinates have not been set in the constructor or with setQualifiedCoordinates method, this method returns the center point of the GeographicArea set as the coverage area. In this case the horizontal and vertical accuracies in the QualifiedCoordinates class are set to Float.NaN.

Returns:

the QualifiedCoordinates of the landmark, null if not available

See Also:

setQualifiedCoordinates(QualifiedCoordinates)

getAddressInfo

public AddressInfo getAddressInfo()

Gets the AddressInfo of the landmark.

Returns:

the AddressInfo of the landmark, null if not available

See Also:

setAddressInfo(AddressInfo)

getIdentifier

public int getIdentifier()

Returns the identifier of the landmark.

Returns:

the landmark's identifier or NO_IDENTIFIER if identifier has not been set

Since:

2.0

See Also:

setIdentifier(int)

getAuthor

public java.lang.String getAuthor()

Returns the author of the landmark.

Returns:

the landmark's author or null if author has not been set

Since:

2.0

See Also:

setAuthor(String)

getGeographicArea

public GeographicArea getGeographicArea()

Returns the coverage area of the landmark.

Returns:

the landmark's coverage area

Since:

2.0

See Also:

setGeographicArea(GeographicArea)

getURL

public java.lang.String[][] getURL()

Returns the two-dimensional array that contains the URLs and descriptions for them set for the landmark. The URL may be a web address or a URL to a local file that contains more content to the landmark. The descriptions contain additional information about the URL and it may be shown to the user. The first index in the pair contains the URL and the second index the corresponding description. The returned array contains the URLs and descriptions pairs in the same order as they were set by the application in the constructor or with the setURL method. If null or an empty array was used in the setter or in the constructor, null is returned.

Returns:

an array of URL information, first element in the pair contains the URL and the second element the corresponding description, null if no URL information has been set

Since:

2.0

See Also:

setURL(String[][])

getExtraInfo

public java.lang.String[] getExtraInfo()

Returns the extra information of the landmark. The returned String array contains the additional landmark information items in the same order as they were set by the application in the constructor or with the setExtraInfo method. If null or an empty array was used in the setter or in the constructor, null is returned.

Returns:

an array of the additional information, null if no extra information has been set

Since:

2.0

See Also:

setExtraInfo(String[])

getTimestamp

public long getTimestamp()

Gets the timestamp of the landmark. Timestamp indicates the time when the landmark information was last modified. The timestamp is updated by the API implementation. The timestamp must be updated when a new landmark object that does not belong to a landmark store is created or when a landmark field is updated to a value different from what get* method returned. Creating a landmark that does not belong to any landmark store means that an application constructs a new landmark object with the constructor.

When Landmark objects are imported to a landmark store, the timestamp is set to the time of import. When landmarks are added to a landmark store or updated in a landmark store the timestamp is updated.

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.currentTimeMillis().

Returns:

the time of the last update on the landmark data

Since:

2.0

setName

public void setName(java.lang.String name)

Sets the name of the landmark.

Parameters:

name - name for the landmark

Throws:

java.lang.NullPointerException - if the parameter is null

See Also:

getName()

setDescription

public void setDescription(java.lang.String 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()

setQualifiedCoordinates

public void setQualifiedCoordinates(QualifiedCoordinates coordinates)

Sets the QualifiedCoordinates of the landmark.

Parameters:

coordinates - the qualified coordinates of the landmark, null may be passed in to indicate that qualified coordinates are not available

See Also:

getQualifiedCoordinates()

setAddressInfo

public void setAddressInfo(AddressInfo addressInfo)

Sets the AddressInfo of the landmark.

Parameters:

addressInfo - the AddressInfo of the landmark, null may be passed in to indicate that address information is not available

See Also:

getAddressInfo()

setIdentifier

public void setIdentifier(int identifier)

Sets the identifier of the landmark. NO_IDENTIFIER can be used to indicate that the identifier has not been set.

Parameters:

identifier - the landmark's identifier,

Throws:

java.lang.IllegalArgumentException - if identifier < -1 (=NO_IDENTIFIER) or identifier = 0

Since:

2.0

setGeographicArea

public void setGeographicArea(GeographicArea area)

Sets the coverage area for the landmark.

Parameters:

area - the area the landmark covers, may be null

Since:

2.0

setAuthor

public void setAuthor(java.lang.String author)

Sets the author or the provider of the landmark data, may be null.

Parameters:

author - landmark's author

Since:

2.0

setURL

public void setURL(java.lang.String[][] urls)

Sets the URLs and their descriptions for a landmark. The URL may be a web address or a URL to a local file that contains more content to the landmark. The descriptions contains additional information about the URL. The description is meant to be shown to the user. The URLs and descriptions are given as a two-dimensional array that is handled as an array inside an array. It means that one URL and description pair is stored in an array, where URL has the index 0 and the description is in index 1. These pair arrays are stores in another array. If the URL in the pair is an empty array, an IllegalArgumentException is thrown. If the URL does not have a description an empty String must be used. If the urls array contains null elements in either as a URL or as a description, a NullPointerException is thrown. Passing null or an empty array indicates no URL and description information is available.

Parameters:

urls - an array of URLs and descriptions for the landmark, where the first elements in the pair contains the URL and the second element the corresponding description, may be null or an empty array

Throws:

java.lang.IllegalArgumentException - if the number of elements in the inner array is not 2 or if any URL element in the inner array of urls parameter is an empty String

java.lang.NullPointerException - if urls contains null elements

Since:

2.0

setExtraInfo

public void setExtraInfo(java.lang.String[] extraInfo)

Sets the additional information to the landmark. This information may be, for example, speed or heading at the landmark. The landmark may have a special meaning only when looking into certain direction. Or the landmark may contain information about the speed limit on that point. The additional information is a String arrays of additional items. Passing null or an empty array indicates no additional information is available.

Parameters:

extraInfo - additional information for the landmark, may be null or an empty array

Since:

2.0

getCategories

public java.lang.String[] getCategories()

Returns the categories this landmark instance is currently added at the time this landmark instance was created. The categories are specific to the landmark store this landmark instance belongs to. The category information is not updated even if the landmark is added to new categories in the landmark store. The landmark store can be retrieved with method getLandmakrStoreName. If the landmark does not belong to any landmark store or is not added to any category, an empty array is returned.

Returns:

the names of the categories the landmark belongs to, an empty array if the landmark does not belong to any landmark store or it has not been added to any category

Since:

2.0

getLandmarkStoreName

public java.lang.String getLandmarkStoreName()

Returns the name of the landmark store this landmark instance currently belongs to at the time this landmark instance was created. The landmark store information is not updated even if the landmark is added to another landmark store. If the landmark belongs to the default landmark store, this method returns the name of that, that is, null. If this landmark does not belong to a landmark store, an empty String is returned.

Returns:

the name of the landmark store this landmark belongs to, an empty String if the landmark does not belong to any landmark store

Since:

2.0

equals

public boolean equals(java.lang.Object landmark)

Overriding the equals method in Object class to compare the equality of values in two Landmark objects. Two Landmark objects are equal if the landmark fields are equal. Timestamp, category information and landmark store name are not taken into account in the field comparisons.

Overrides:

equals in class java.lang.Object

Parameters:

landmark - the Landmark object to which the comparison is done

Returns:

true if all fields, excluding timestamp, category names and landmark store name, in the objects are equal, else false

hashCode

public int hashCode()

Overriding the hashCode method in Object class. The method returns a hash code value for the landmark object. Two Landmark objects that are equal must have the same hash code. For more information see java.lang.Object.hashCode() method.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code of the landmark