org.placelab.jsr0179
Class FSLandmarkStore

java.lang.Object
  javax.microedition.location.LandmarkStore
      org.placelab.jsr0179.FSLandmarkStore

public class FSLandmarkStore

extends javax.microedition.location.LandmarkStore

Filesystem-based implementation of a JSR-179 LandmarkStore. NOTE: The way this store works isn't completely consistent with how you would expect the LandmarkStore to operate in regards to categories. In the spec, a landmark exists in one place but can be associated with one or more categories. In this implementation, a landmark is physically tied to a category, and is stored in a category file. It exists in the store as many times as the categories it belongs to.

Constructor Summary

FSLandmarkStore()

Method Summary

void	addCategory(java.lang.String categoryName) Adds a category to this LandmarkStore.
void	addLandmark(javax.microedition.location.Landmark landmark, java.lang.String category) Adds a landmark to the specified group in the landmark store.
void	deleteCategory(java.lang.String categoryName) Removes a category from this LandmarkStore.
void	deleteLandmark(javax.microedition.location.Landmark landmark) Deletes a landmark from this LandmarkStore.
java.util.Enumeration	getCategories() Returns the category names that are defined in this LandmarkStore.
java.util.Enumeration	getLandmarks() Lists all landmarks stored in the store.
java.util.Enumeration	getLandmarks(java.lang.String category, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude) Lists all the landmarks that are within an area defined by bounding minimum and maximum latitude and longitude and belong to the defined category, if specified.
java.util.Enumeration	getLandmarks(java.lang.String category, java.lang.String name) Gets the Landmarks from the storage where the category and/or name matches the given parameters.
protected static javax.microedition.location.Landmark	landmarkFromString(java.lang.String str)
protected static java.lang.String	landmarkToString(javax.microedition.location.Landmark landmark)
void	removeLandmarkFromCategory(javax.microedition.location.Landmark lm, java.lang.String category) Removes the named landmark from the specified category.

Methods inherited from class javax.microedition.location.LandmarkStore

createLandmarkStore, deleteLandmarkStore, getInstance, listLandmarkStores, updateLandmark

Methods inherited from class java.lang.Object

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

Constructor Detail

FSLandmarkStore

public FSLandmarkStore()
                throws java.lang.Exception

Method Detail

addCategory

public void addCategory(java.lang.String categoryName)
                 throws java.io.IOException

Description copied from class: javax.microedition.location.LandmarkStore

Adds a category to this LandmarkStore. All implementations must support names that have length up to and including 32 characters. If the provided name is longer it may be truncated by the implementation if necessary.

Parameters:

categoryName - name for the category to be added

Throws:

java.io.IOException - if an I/O error occurs or there are no resources to add a new category

addLandmark

public void addLandmark(javax.microedition.location.Landmark landmark,
                        java.lang.String category)
                 throws java.io.IOException

Description copied from class: javax.microedition.location.LandmarkStore

Adds a landmark to the specified group in the landmark store. If some textual String field inside the landmark object is set to a value that is too long to be stored, the implementation is allowed to automatically truncate fields that are too long. However, the name field MUST NOT be truncated. Every implementation shall be able to support name fields that are 32 characters or shorter. Implementations may support longer names but are not required to. If an application tries to add a Landmark with a longer name field than the implementation can support, IllegalArgumentException is thrown. When the landmark store is empty, every implementation is required to be able to store a landmark where each String field is set to a 30 character long string. If the Landmark object that is passed as a parameter is an instance that belongs to this LandmarkStore, the same landmark instance will be added to the specified category in addition to the category/categories which it already belongs to. If the landmark already belongs to the specified category, this method returns with no effect. If the landmark has been deleted after obtaining it from getLandmarks, it will be added back when this method is called. 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, 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, the Landmark object that is passed as a parameter belongs to this LandmarkStore.

Parameters:

landmark - the landmark to be added

category - category where the landmark is added. null can be used to indicate that the landmark does not belong to a category

Throws:

java.io.IOException - if an I/O error happened when accessing the landmark store or if there are no resources available to store this landmark

deleteCategory

public void deleteCategory(java.lang.String categoryName)
                    throws java.io.IOException

Description copied from class: javax.microedition.location.LandmarkStore

Removes a category from this LandmarkStore. The category will be removed from all landmarks that are in that category. However, this method will not remove any of the landmarks, only the associated category information from the landmarks. If a category with the supplied name does not exist in this LandmarkStore, the method returns silently with no error.

Parameters:

categoryName - name for the category to be removed

Throws:

java.io.IOException - if an I/O error occurs

deleteLandmark

public void deleteLandmark(javax.microedition.location.Landmark landmark)
                    throws java.io.IOException

Description copied from class: javax.microedition.location.LandmarkStore

Deletes a landmark from this LandmarkStore. This method removes the specified landmark from all categories and deletes the information from this LandmarkStore. The Landmark instance passed in as the parameter must be an instance that belongs to this LandmarkStore. If the Landmark is not found in this LandmarkStore, then the request is silently ignored and the method call returns with no error.

Parameters:

landmark - the landmark to be deleted

Throws:

java.io.IOException - if an I/O error happened when accessing the landmark store

getCategories

public java.util.Enumeration getCategories()

Description copied from class: javax.microedition.location.LandmarkStore

Returns the category names that are defined in this LandmarkStore. The language and locale used for these names depends on the implementation and end user settings. The names shall be such that they can be displayed to the end user and have a meaning to the end user

Returns:

an java.util.Enumeration containing Strings representing the category names. If there are no categories defined in this LandmarkStore, an Enumeration with no entries is returned.

getLandmarks

public java.util.Enumeration getLandmarks()
                                   throws java.io.IOException

Description copied from class: javax.microedition.location.LandmarkStore

Lists all landmarks stored in the store.

Returns:

a java.util.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.io.IOException - if an I/O error happened when accessing the landmark store

getLandmarks

public java.util.Enumeration getLandmarks(java.lang.String category,
                                          double minLatitude,
                                          double maxLatitude,
                                          double minLongitude,
                                          double maxLongitude)
                                   throws java.io.IOException

Description copied from class: javax.microedition.location.LandmarkStore

Lists all the landmarks that are within an area defined by bounding minimum and maximum latitude and longitude and belong to the defined category, if specified. The bounds are considered to belong to the area. If minLongitude <= maxLongitude, this area covers the longitude range [minLongitude, maxLongitude]. If minLongitude > maxLongitude, this area covers the longitude range [-180.0, maxLongitude] and [minLongitude, 180.0). For latitude, the area covers the latitude range [minLatitude, maxLatitude].

Parameters:

category - the category of the landmark. null implies a wildcard that matches all categories

minLatitude - minimum latitude of the area. Must be within the range [-90.0, 90.0]

maxLatitude - maximum latitude of the area. Must be within the range [minLatitude, 90.0]

minLongitude - minimum longitude of the area. Must be within the range [-180.0, 180.0)

maxLongitude - maximum longitude of the area. Must be within the range [-180.0, 180.0)

Returns:

an Enumeration containing all the matching Landmarks or null if no Landmark matched the given parameters

Throws:

java.io.IOException - if an I/O error happened when accessing the landmark store

getLandmarks

public java.util.Enumeration getLandmarks(java.lang.String category,
                                          java.lang.String name)
                                   throws java.io.IOException

Description copied from class: javax.microedition.location.LandmarkStore

Gets the Landmarks from the storage where the category and/or name matches the given parameters.

Parameters:

category - the category of the landmark. null implies a wildcard that matches all categories

name - the name of the desired landmark. null implies a wildcard that matches all the names within

Returns:

an Enumeration containing all the matching Landmarks or null if no Landmark matched the given parameters

Throws:

java.io.IOException - if an I/O error happened when accessing the landmark store

removeLandmarkFromCategory

public void removeLandmarkFromCategory(javax.microedition.location.Landmark lm,
                                       java.lang.String category)
                                throws java.io.IOException

Description copied from class: javax.microedition.location.LandmarkStore

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. 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, then the request is silently ignored and the method call returns with no error. The request is also silently ignored if the specified category does not exist in this LandmarkStore. The landmark is only removed from the specified category but the landmark information is retained in the store. If the landmark no longer belongs to any category, it can still be obtained from the store by passing null as the category to getLandmarks.

Parameters:

lm - the landmark to be removed

category - the category from which it will be removed.

Throws:

java.io.IOException - if an I/O error happened when accessing the landmark store

landmarkFromString

protected static javax.microedition.location.Landmark landmarkFromString(java.lang.String str)

landmarkToString

protected static java.lang.String landmarkToString(javax.microedition.location.Landmark landmark)