LandmarkStore (Oracle Java Wireless Client)

java.lang.Object
- com.cinterion.location.LandmarkStore

```
public class LandmarkStore
extends Object
```
The class LandmarkStore provides a database for writing, reading and deleting landmarks. The landmark store is persistent. The stores are saved to FFS under a:/lmstores/store_X.xml, where X is the number of the store (0 is the default store). There can be 7 stores plus 1 default store each containing up to 100 landmarks in up to 8 categories ("no category" also counts as a category). There is only one store active at a time. The current store information is kept in RAM and only written to FFS when the application switches to a different store or terminates. Saving a store might take up to 45s! During this time period the VM is blocked, no processing can be done in parallel. All landmark stores are shared between all J2ME applications. After removing any files from directory 'lmstores' or the directory itself, please make a module restart.
A landmark is defined in the class Landmark, it consists of a name, the coordinates, an optional description and optional address information (AddressInfo). Using AddressInfo with the landmarks might decrease the maximum number of possible landmarks in a store, depending on the amount of AddressInfo data being used. An IOException indicates that a store is full.
Each Landmark can be placed in one or more categories. Categories can be used for grouping similar landmarks.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addCategory(String categoryName)` Adds a category to this `LandmarkStore`.
`void`	`addLandmark(Landmark landmark, String category)` Adds a landmark to the specified category in the landmark store.
`static void`	`createLandmarkStore(String storeName)` Creates a new empty landmark store.
`void`	`deleteCategory(String categoryName)` Removes a category from this `LandmarkStore`.
`void`	`deleteLandmark(Landmark lm)` Deletes a landmark from this `LandmarkStore`.
`static void`	`deleteLandmarkStore(String storeName)` Deletes a landmark store.
`Enumeration`	`getCategories()` Returns the category names that are defined in this `LandmarkStore`.
`static LandmarkStore`	`getInstance(String storeName)` Returns an instance of `LandmarkStore`, which can be used for storing, retrieving and deleting landmarks.
`Enumeration`	`getLandmarks()` Returns all landmarks stored in the landmark store.
`Enumeration`	`getLandmarks(String category, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude)` Lists all the landmarks that are within an area.
`Enumeration`	`getLandmarks(String category, String name)` Returns all landmarks where the category and/or name matches the given parameters.
`static String[]`	`listLandmarkStores()` Returns the names of all the available landmark stores.
`void`	`removeLandmarkFromCategory(Landmark lm, String category)` Removes a landmark from the given category.
`void`	`updateLandmark(Landmark lm)` Updates the information about a landmark.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getInstance
```
public static LandmarkStore getInstance(String storeName)
```
    Returns an instance of LandmarkStore, which can be used for storing, retrieving and deleting landmarks.
    
    Parameters:
    storeName - name of the landmark store or zero for opening the default landmark store
    
    Returns:
    the LandmarkStore object or null if a landmark store with the specified name does not exist.
  - createLandmarkStore
```
public static void createLandmarkStore(String storeName)
                                throws IOException,
                                       LandmarkException
```
    Creates a new empty landmark store.
    
    Parameters:
    storeName - the name of the landmark store to create
    
    Throws:
    
    NullPointerException - if the parameter is null
    
    IllegalArgumentException - if the name is too long or if a landmark store with the specified name already exists
    
    IOException - if the landmark store couldn't be created due to an I/O error
    
    LandmarkException
  - deleteLandmarkStore
```
public static void deleteLandmarkStore(String storeName)
                                throws IOException,
                                       LandmarkException
```
    Deletes a landmark store. All stored data will be removed
    If there is no landmark store with the given name, this method returns without any error.
    
    Parameters:
    storeName - the name of the landmark store to create
    
    Throws:
    
    NullPointerException - if the parameter is null (the default landmark store can't be deleted)
    
    IOException - if the landmark store couldn't be deleted due to an I/O error
    
    LandmarkException
  - listLandmarkStores
```
public static String[] listLandmarkStores()
                                   throws IOException
```
    Returns the names of all the available landmark stores. The default landmark store is not included in this list. null is returned, if there are no landmark stores, other than the default landmark store
    
    Returns:
    an array of landmark store names
    
    Throws:
    
    IOException - if an I/O error occurred when trying to access the landmark stores
  - addLandmark
```
public void addLandmark(Landmark landmark,
               String category)
                 throws IOException
```
    Adds a landmark to the specified category in the landmark store.
    The maximum name length is 32 characters. For longer names the IllegalArgumentException is thrown.
    If there is sufficient memory, all other string fields of the landmark store can be 30 characters long. To long values will be truncated automatically.
    
    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:
    
    IllegalArgumentException - if the landmark name is longer than 32 characters or the specified category cannot be found in this LandmarkStore
    
    IOException - if an I/O error happened when accessing the landmark database or if there are no resources available to store this landmark
    
    NullPointerException - if the landmark parameter is null
  - getLandmarks
```
public Enumeration getLandmarks(String category,
                       String name)
                         throws IOException
```
    Returns all landmarks where the category and/or name matches the given parameters.
    
    Parameters:
    category - the category of the landmark. null matches all categories
    name - the name of the landmark. null matches all names
    
    Returns:
    an Enumeration containing all the matching Landmarks or null if no Landmark matched the given parameters
    
    Throws:
    
    IOException - if an I/O error happened when accessing the landmark database
  - getLandmarks
```
public Enumeration getLandmarks()
                         throws IOException
```
    Returns all landmarks stored in the landmark store.
    
    Returns:
    an Enumeration object containing Landmark objects representing all the landmarks stored in this LandmarkStore or null if there ^ are no landmarks in the store
    
    Throws:
    
    IOException - if an I/O error happened when accessing the landmark database
  - getLandmarks
```
public Enumeration getLandmarks(String category,
                       double minLatitude,
                       double maxLatitude,
                       double minLongitude,
                       double maxLongitude)
                         throws IOException
```
    Lists all the landmarks that are within an 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:
    
    IOException - if an I/O error happened when accessing the landmark database
    
    IllegalArgumentException - if the minLongitude or maxLongitude is out of the range [-180.0, 180.0), or minLatitude or minLongitude is out of the range [-90.0,90.0], or if minLatitude > maxLatitude
  - removeLandmarkFromCategory
```
public void removeLandmarkFromCategory(Landmark lm,
                              String category)
                                throws IOException
```
    Removes a landmark from the given category. The landmark has to be an instance, that has been retrieved with getLandmarks.
    This method returns without any error, if the landmark or the category is not found.
    
    Parameters:
    lm - the landmark to be removed
    category - the category from which it will be removed.
    
    Throws:
    
    IOException - if an I/O error happened when accessing the landmark database
  - updateLandmark
```
public void updateLandmark(Landmark lm)
                    throws IOException,
                           LandmarkException
```
    Updates the information about a landmark. The landmark has to be an instance, that has been retrieved with getLandmarks.
    
    Parameters:
    lm - the landmark to be updated
    
    Throws:
    
    LandmarkException - if the landmark instance passed as the parameter has not been obtained using getLandmarks or does not exist in the database any more
    
    IOException - if an I/O error happened when accessing the landmark database
  - deleteLandmark
```
public void deleteLandmark(Landmark lm)
                    throws IOException,
                           LandmarkException
```
    Deletes a landmark from this LandmarkStore. The landmark has to be an instance, that has been retrieved with getLandmarks.
    This method returns without any error, if the landmark is not found.
    
    Parameters:
    lm - the landmark to be deleted
    
    Throws:
    
    LandmarkException - if the landmark instance passed as the parameter has not been obtained using getLandmarks
    
    IOException - if an I/O error happened when accessing the landmark database
  - getCategories
```
public Enumeration getCategories()
```
    Returns the category names that are defined in this LandmarkStore.
    
    Returns:
    an Enumeration containing Strings representing the category names. If there are no categories defined in this LandmarkStore, an Enumeration with no entries is returned.
  - addCategory
```
public void addCategory(String categoryName)
                 throws LandmarkException,
                        IOException
```
    Adds a category to this LandmarkStore.
    The maximum category name length is 32 characters long. Longer names will be truncated.
    
    Parameters:
    categoryName - name for the category to be added
    
    Throws:
    
    IllegalArgumentException - if a category with the specified name already exists.
    
    NullPointerException - if the parameter is null
    
    LandmarkException - if this LandmarkStore does not support adding new categories
    
    IOException - if an I/O error occurs or there are no resources to add a new category
  - deleteCategory
```
public void deleteCategory(String categoryName)
                    throws LandmarkException,
                           IOException
```
    Removes a category from this LandmarkStore. This implies to remove all stored landmarks from this category. The landmarks itself will remain in the database. This methods will return without any error, if the specified category is not found in the database.
    
    Parameters:
    categoryName - name for the category to be removed
    
    Throws:
    
    NullPointerException - if the parameter is null
    
    LandmarkException - if this LandmarkStore does not support deleting categories
    
    IOException - if an I/O error occurs

Class LandmarkStore

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getInstance

createLandmarkStore

deleteLandmarkStore

listLandmarkStores

addLandmark

getLandmarks

getLandmarks

getLandmarks

removeLandmarkFromCategory

updateLandmark

deleteLandmark

getCategories

addCategory

deleteCategory