net.sf.mmm.search.engine.api

Interface SearchEngine

All Known Subinterfaces:

ManagedSearchEngine

All Known Implementing Classes:

AbstractSearchEngine, LuceneSearchEngine

public interface SearchEngine

This is the interface of a search-engine used to perform full-text search. An implementation of this interface has to be thread-safe.

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
long	count(String field, String value) This method counts the number of SearchEntrys where the given field has the given value.
SearchEntry	getEntry(String entryId) This method gets a entry by its technical entry-ID.
SearchQueryBuilder	getQueryBuilder() This method gets the query builder user to create and parse queries.
long	getTotalEntryCount() This method gets the total number of SearchEntrys in the search-index.
SearchResultPage	search(SearchQuery query, int hitsPerPage) This method performs an initial search for a given query and returns the first SearchResultPage.
SearchResultPage	search(SearchQuery query, int hitsPerPage, int pageIndex, int totalHitCount) This method performs a search for a subsequent SearchResultPage of an initial search.

Method Detail

getQueryBuilder

SearchQueryBuilder getQueryBuilder()

This method gets the query builder user to create and parse queries.

Returns:

the query builder of this engine.

search

SearchResultPage search(SearchQuery query,
                        int hitsPerPage)
                 throws SearchException

This method performs an initial search for a given query and returns the first SearchResultPage. The hits are in descending order of their score so the best hit is the first hit of the page .
For getting the results of a following SearchResultPage use search(SearchQuery, int, int, int).

Parameters:

query - is the query of the user that wants to search. Use the query-builder to construct.

hitsPerPage - is the number of hits per page. See SearchResultPage.DEFAULT_HITS_PER_PAGE.

Returns:

the search result page for the given query at the given pageIndex.

Throws:

SearchException - if the search can NOT be performed for technical reasons.

See Also:

getQueryBuilder()

search

SearchResultPage search(SearchQuery query,
                        int hitsPerPage,
                        int pageIndex,
                        int totalHitCount)
                 throws SearchException

This method performs a search for a subsequent SearchResultPage of an initial search. The hits are in descending order of their score.

Parameters:

query - is the query of the user that wants to search. Use the query-builder to construct.

hitsPerPage - is the number of hits contained in a SearchResultPage. This should be the same value as in the initial search.

pageIndex - is the page index of the requested search result. For a new query this should initially be 0. After a search result was retrieved by this method, further calls for the same query can be performed with a pageIndex greater than 0 and less than SearchResultPage.getPageCount().
It can NOT be guaranteed that the pageIndex is always valid in the sense as described above (the search index may have been modified in the meantime). An implementation has to be able to handle calls with a pageIndex greater or equal to SearchResultPage.getPageCount(). The recommended strategy is to return the last page in this case.

totalHitCount - is the total hit count expected for this query that is already known from the initial search. The implementation has to be able to handle that the search index may have been modified in the meantime and the value is NOT correct anymore. If the implementation can determine the correct total hit-count without performance overhead, it may ignore this parameter.

Returns:

the search result page for the given query at the given pageIndex.

Throws:

SearchException - if the search can NOT be performed for technical reasons.

count

long count(String field,
           String value)

This method counts the number of SearchEntrys where the given field has the given value. This can be useful for counting the SearchEntrys of a particular source or type. You could also do a search to figure this out but this method is supposed to be much faster.

Parameters:

field - is the name of the field.

value - is the potential value to match.

Returns:

the number of matching SearchEntrys.

getTotalEntryCount

long getTotalEntryCount()

This method gets the total number of SearchEntrys in the search-index.

Returns:

the total number of SearchEntrys.

getEntry

SearchEntry getEntry(String entryId)
              throws SearchException

This method gets a entry by its technical entry-ID.
This method may be useful for getting details of a hit in a new request (without rerunning the search).

Parameters:

entryId - is the ID of the requested entry.

Returns:

the entry with the given id or null if no such entry is available.

Throws:

SearchException - if the operation failed for technical reasons.