Landmark store management

The LandmarkStore class contains a set of landmark management methods. Enumeration of Landmark objects can be obtained with one of the three getLandmarks() methods. The first method does not use parameters and provides a list of all stored landmarks in a specific landmark store. The other two methods can be used to fetch only the landmarks that match the set parameters. The second method can be seen in Code sample 9. In this example, one can obtain a list of landmarks from a specified category that are within a defined area and bounded by the min and max latitude and longitude positions. The third getLandmarks() method can be used to list landmarks within a specific category.

Code sample 9: Listing landmarks from a specific area and category

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

New landmarks can be added to the landmark store with the addLandmark(Landmark landmark, String category) method. An added landmark will be associated with the specified category. A null category parameter indicates that a landmark does not belong to any category. If a landmark object passed as a parameter already belongs to the landmark store, the same landmark instance will be added to the specified category or categories it already belongs to. The sequence diagram in below figure shows how a new Landmark object is generated and added to the landmark store in the TouristRoute MIDlet.

Figure 164: Sequence diagram of adding a new landmark in the TouristRoute example MIDlet

An existing landmark in the landmark store can be updated by using the updateLandmark(Landmark landmark) method. This method throws LandmarkException if the landmark passed as a parameter does not belong to the landmark store. In addition, landmark removal from the landmark store can be done with the deleteLandmark(Landmark lm) method. Also this method throws LandmarkException if the landmark passed as a parameter does not belong to the store. Furthermore, an existing Landmark object can also be removed only from the specific category with the removeLandmarkFromCategory (Landmark lm, String category) method.

Before using these three landmark store management methods, an instance of the Landmark object must exist. The constructor of the Landmark class requires the name, description, qualified coordinates, and address info parameters. QualifiedCoordinates for the landmark can be obtained, for example, from the LocationListner.locationUpdated() method's location parameter.

Code sample 10 shows how the TouristRoute example MIDlet creates a new AddressInfo instance and passes it to Landmark's constructor. AddressInfo is a container class that holds textual address information about the location. It has only two methods: getField(int field) for getting field values, and setField(int field, String value) for setting the values. The AddressInfo class contains a set of constant int field values that should be used in the parameters passed to those two methods (see Code sample 10).

Code sample 10: Creating a landmark instance in the TouristRoute MIDlet (TouristRoute's LandmarkEditorUI.java class)

AddressInfo info = new AddressInfo();
info.setField(AddressInfo.COUNTRY, countryField.getString());
info.setField(AddressInfo.STATE, stateField.getString());
info.setField(AddressInfo.CITY, cityField.getString());
info.setField(AddressInfo.STREET, streetField.getString());
info.setField(AddressInfo.BUILDING_NAME, buildingNameField.getString());

Landmark lm = new Landmark(nameField.getString(),
                           descField.getString(),
                           coord,
                           info);