Figure 1: Landmarks API classes
Landmarks Search API is mainly targeted for end-user applications. It lets clients search for landmarks and landmark categories in landmark databases.
The logical type of this interface is Library API. Technically this is a method-call API. Landmarks Search API loads the implementation at run time but the implementation consists only of local objects.
The following sections describe the Landmarks Search API class structure. UML diagrams are used to present the classes and their dependencies.
Note: The UML diagrams do not show all the available functions, and some or all function parameters may be left out.
The Landmarks Search API allows searching in a single database or in multiple
databases by means of CPosLandmarkSearch and CPosLmMultiDbSearch respectively.
CPosLandmarkSearch is mainly used to start searches
and to obtain the search matches. The client has to specify the landmark database
to search when CPosLandmarkSearch is instantiated. CPosLandmarkSearch returns
a CPosLmOperation instance, which is used to execute the
search operation incrementally or all at once (see Incremental
execution in Landmarks API specification). If the
operation is run incrementally, the client can check the operation progress
between the incremental steps. CPosLmItemIterator with
the IDs of the search matches can be obtained from CPosLandmarkSearch.
CPosLmMultiDbSearch is used to search for landmarks
and landmark categories in several landmark databases. The client specifies
the URIs of the landmark databases to be searched. CPosLmMultiDbSearch returns
a CPosLmOperation instance, which is used to execute the
search operation incrementally or all at once. If the operation is run incrementally,
the client can check the operation progress between the incremental steps. CPosLmItemIterator with
the IDs of the search matches can be obtained from CPosLmMultiDbSearch.
CPosLandmarkDatabase, CPosLmItemIterator and CPosLmOperation are
parts of Landmarks API and they are described further in Landmarks API specification.
Figure 1: Landmarks API classes
CPosLmSearchCriteria is a base class for search criterion
classes in Landmarks Search API. Criterion classes are used to specify what
criteria a landmark must fulfill in order to be a search match. There are
several search criterion classes in Landmarks Search API.
Figure 2: Search criterion classes
| Criterion class | Description |
CPosLmCategoryCriteria
|
Used for searching landmarks, which contain a certain category, or landmarks, which do not contain any categories. |
CPosLmTextCriteria
|
Used for searching landmarks, which contain a certain text. |
CPosLmAreaCriteria
|
Used for searching landmarks, which reside in a certain area. |
CPosLmNearestCriteria
|
Used for finding landmarks, which are closest to a certain coordinate. |
CPosLmCompositeCriteria
|
Used for searching landmarks by combining multiple search criteria. |
CPosLmIdListCriteria
|
Used if the client only wants to search a subset of the landmarks in a database. |
CPosLmCatNameCriteria
|
Used for searching landmark categories with a certain name. |
When using the landmark item iterator to retrieve search matches, the matches will not be sorted until the search operation has completed. If the client needs a sorted list of the matches before the search has completed, e.g. it wants to show matches in a sorted list as they are found to the application user, the display data feature should be used instead.
Before a search is started, the client specifies CPosLmDisplayData to
be used in the search. When the search is executing, the matching categories
or landmarks are read from the database and added to CPosLmDisplayData. CPosLmDisplayItem holds
the matching CPosLandmark or CPosLandmarkCategory together
with the index of the database where the match was found. The database index
is only used when searching in several databases.
Figure 3: Result classes
