net.sf.mmm.search.indexer.api

Interface SearchIndexer

All Superinterfaces:

AutoCloseable, Closeable, Flushable

All Known Implementing Classes:

AbstractSearchIndexer, LuceneSearchIndexer

public interface SearchIndexer
extends Flushable, Closeable

This is the interface for the indexer used to create and modify a search index. After a search-index is created, the contained information can be searched and found via a SearchEngine.

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

SearchIndexerBuilder

Method Summary

Modifier and Type	Method and Description
void	add(MutableSearchEntry entry) This method adds the given entry to the search-index.
void	close() This method closes the search index.
MutableSearchEntry	createEntry() This method creates a new and empty entry for the search-index.
void	flush() This method flushes the search index what ensures that all changes are written to the index.
SearchEngine	getSearchEngine() This method gets the SearchEngine for the index of this SearchIndexer.
void	optimize() This method optimizes the search index.
boolean	remove(SearchHit hit) This method removes an existing entry identified by the given hit.
int	remove(String field, Object value) This method removes all existing entries identified by the given value at the given property from the search-index.
int	removeByCustumId(String cid) This method removes an existing entry identified by the given uri from the search-index.
boolean	removeById(Long entryId) This method removes an existing entry identified by the given id from the search-index.
int	removeByUri(String uri, String sourceId) This method removes an existing entry identified by the given uri from the search-index.
int	update(MutableSearchEntry entry) This method updates the given entry in the search-index.

Method Detail

createEntry

MutableSearchEntry createEntry()

This method creates a new and empty entry for the search-index. After the entry is filled with data, use add(MutableSearchEntry) to add it to the search index.

Returns:

a new and empty search-index entry.

add

void add(MutableSearchEntry entry)
  throws SearchException

This method adds the given entry to the search-index.

Parameters:

entry - is the entry to add.

Throws:

SearchException - if the operation failed.

update

int update(MutableSearchEntry entry)
    throws SearchException

This method updates the given entry in the search-index. This method will use the property SearchEntry.FIELD_CUSTOM_ID to identify a potentially existing entry to update. Otherwise it will use a combination of SearchEntry.FIELD_URI and SearchEntry.FIELD_SOURCE as identifier (what is NOT a very strong ID as the URI can change).

Parameters:

entry - is the entry to update.

Returns:

the number of entries that have been replaced. This should typically be 1 if one entry was replaced or 0 none was replaced and the given entry has only been added. A value greater than 1 indicates that multiple entries have been replaced that all have the same identifier what indicates a mistake of your index or the indexer.

Throws:

SearchException - if the operation failed.

removeById

boolean removeById(Long entryId)
            throws SearchException

This method removes an existing entry identified by the given id from the search-index.
ATTENTION:
If you are using lucene as implementation according to some questionable design of lucene this method has to close the IndexWriter and create an IndexReader to perform the delete. If you invoke an other method after that the same has to be done reverse. This can cause really bad performance.

Parameters:

entryId - is the ID of the entry to remove (NOT null).

Returns:

true if the entry existed and has been removed from the index, false if NO entry exists for the given id.

Throws:

SearchException - if the operation failed.

remove

boolean remove(SearchHit hit)
        throws SearchException

This method removes an existing entry identified by the given hit. In most cases this method will delegate to removeById(Long). However the implementation can decide what is the best way to do it.

Parameters:

hit - is the SearchHit to remove.

Returns:

true if the entry existed and has been removed from the index, false if NO entry exists for the given hit.

Throws:

SearchException - if the operation failed.

removeByCustumId

int removeByCustumId(String cid)
              throws SearchException

This method removes an existing entry identified by the given uri from the search-index.

Parameters:

cid - is the custom-ID of an entry previously added to the index.

Returns:

the number of entries that have been removed. This should typically be 1 if one entry exists with the given uid or 0 if no such entry exists. A value greater than 1 indicates that multiple entries have been removed that all have the given uid what indicates a mistake of your index(er). A value of -1 means the number is unknown because this is not supported by the implementation.

Throws:

SearchException - if the operation failed.

See Also:

update(MutableSearchEntry)

removeByUri

int removeByUri(String uri,
                String sourceId)
         throws SearchException

This method removes an existing entry identified by the given uri from the search-index.

Parameters:

uri - is the URI of an entry previously added to the index.

sourceId - is the ID of the SearchSource. This is required because the uri itself may NOT be unique (e.g. different sources might both contain the entry with URI "index.html").

Returns:

the number of entries that have been removed. This should typically be 1 if one entry exists with the given uri or 0 if no such entry exists. A value greater than 1 indicates that multiple entries have been removed that all have the given uri. A value of -1 means the number is unknown because this is not supported by the implementation.

Throws:

SearchException - if the operation failed.

See Also:

update(MutableSearchEntry)

remove

int remove(String field,
           Object value)
    throws SearchException

This method removes all existing entries identified by the given value at the given property from the search-index.
ATTENTION:
Please use this method with care.

Parameters:

field - is the name of the field where the value is expected to occur. Therefore the field should NOT to be of the type SearchFieldType.TEXT.

value - is the value of the field.

Returns:

the number of entries that have been removed or -1 if the number is unknown because this is not supported by the implementation.

Throws:

SearchException - if the operation failed.

flush

void flush()
    throws SearchException

This method flushes the search index what ensures that all changes are written to the index. If NOT supported by the implementation, this method will have no effect.

Specified by:

flush in interface Flushable

Throws:

SearchException - if the operation failed.

optimize

void optimize()
       throws SearchException

This method optimizes the search index. If NOT supported by the implementation, this method will have no effect. Optimization will typically cause some performance overhead but therefore speed up your searches.

Throws:

SearchException - if the operation failed.

getSearchEngine

SearchEngine getSearchEngine()

This method gets the SearchEngine for the index of this SearchIndexer. It may be used for advanced indexing where search-queries need to performed for updating the search-index.

Returns:

the SearchEngine.

close

void close()
    throws SearchException

This method closes the search index. After the call of this method no other method of this object shall be invoked.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

SearchException - if the operation failed.