com.sssw.search.api
Interface EbiQuery

All Superinterfaces:

EbiQueryBase, Serializable

public interface EbiQuery

extends EbiQueryBase, Serializable

The Query interface. Objects that implement this interface represent queries executed via the Search Service's Query Engine.

The following is an example of running a query:

 // Instantiate a blank query object
 com.sssw.search.api.EbiQuery query = com.sssw.search.factory.EboFactory.getQuery();
 // The query type will be "text"
 query.setQueryType(query.QUERY_TYPE_TEXT);
 // Specify the actual query
 query.setText("movies+science+fiction");
 // Provide any field specifiers (want movie reviews whose genre is comedy)
 String fieldSpecList = "fnameDOCTYPENAME=*MovieReview*+fnameGenre=*Comedy*"
 String fieldBooleanExpr = "fnameDOCTYPENAME+AND+fnameGenre";
 query.setFieldSpecList(fieldSpecList, fieldBooleanExpr);
 // Use the batch mode to paginate through results -- get the first 10
 query.setBatchOptions(0, 10);
 // Narrow the scope by date
 query.setDateRange(Timestamp.valueOf("1999-03-05 12:00:00"), new java.util.Date());
 // We want quick summaries generated
 query.setGenerateQuickSummary(true);
 // We want at most 100 results for this query
 query.setMaxNumResults(100);
 // We only want 70% and up relevance
 query.setRelevanceCut(70);
 // Sort results by date
 query.setSortByDate(true);
 // Sort results by relevance
 query.setSortByRelevance(true);

 // Get the query engine
 EbiQueryEngine qe = com.sssw.search.factory.EboFactory.getQueryEngine();
 // Run the query
 Iterator iterResults = qe.runQuery(context, query, null, true).iterator();
 // Process the results
 while (iterResults.hasNext()) {
 	com.sssw.search.api.EbiQueryResult res = (com.sssw.search.api.EbiQueryResult)iterResults.next();
 	System.out.println(res);
 }
 

Field Summary

static int	QUERY_TYPE_FUZZY Fuzzy query type.
static int	QUERY_TYPE_GETALL The "get all documents" query type.
static int	QUERY_TYPE_NAMESEARCH The "name search" query type to search for proper names.
static int	QUERY_TYPE_SUGGEST The "suggest similar documents" query type.
static int	QUERY_TYPE_TEXT Basic text query type.

Method Summary

boolean	allSelected() Returns true if all document properties have been selected.
void	clear() Clears any information set into the query by the caller.
void	deselectAll() Deselects all the properties that the caller previously selected.
void	fromXML(Node xmlData) Initializes this query object from XML data.
int	getBatchSize() Returns the batch size for batch queries.
int	getBatchStart() Returns the batch size for batch queries.
Date	getDateRangeEnd() Returns the end of the date range, if one has been specified.
Date	getDateRangeStart() Returns the start of the date range, if one has been specified.
String[]	getExclusions() Returns the list of any document exclusions from the query results.
String	getFieldBooleanExpr() Returns the field Boolean expression, if one has been specified.
String	getFieldSpecList() Returns the field specifier list.
int	getMaxNumResults() Returns the maximum number of results to be returned.
int	getQueryType() Returns the query type.
int	getRelevanceCut() Returns the relevance cut for query results.
Collection	getSelects() Returns the list of selected document properties.
String	getText() Returns the query text.
EbiRepositoryDesc	getThesaurus() Returns the Thesaurus options set up for this Query object, if any.
boolean	isBatched() Returns true if the the query is being run in batch mode.
boolean	isSelected(String propName) Returns true if the specified property is selected.
boolean	isThesaurusQuery() Returns true if this Query is marked to run as a thesaurus query.
boolean	mustExcludeSuggestDocs() Returns true if the documents whose identifiers are specified in the query text are to be excluded from the query results.
boolean	mustGenerateQuickSummary() Returns true if quick summaries are to be generated for each of the query results.
boolean	mustSortByDate() Returns true if query results are to be sorted by date.
boolean	mustSortByRelevance() Returns true if query results are to be sorted by relevance.
boolean	mustUseAbsWeight() Returns true if relevance scores are to be returned per document as absolute weights rather than percentages.
boolean	mustUseExclusionsAsIDs() Returns true if any specified exclusions should be treated as document ID's.
boolean	mustUseIDsForSuggest() Returns true if the document identifiers supplied in the query text are to be treated as document IDs.
boolean	removeSelect(String propName) Removes the specified property from the list of selected properties.
void	select(String propName) Selects a specific property.
void	selectAll() Selects all available document properties to be returned in the query results.
void	selectAlways(String propName) Specifies that the given property is always to be selected.
void	setBatchOptions(int batchStart, int batchSize) Sets options for retrieving a batch ("pageful") of query results instead of retrieving all results in a single request.
void	setDateRange(Date from, Date to) Sets the date range (optional).
void	setExclusions(String[] exclusions, boolean useAsIDs) Specifies any exclusions from the query results.
void	setFieldSpecList(String fieldSpecList, String fieldBooleanExpr) Sets the field specifier list.
void	setGenerateQuickSummary(boolean generate) Specifies that quick summaries are to be generated for each of the query results.
void	setIsThesaurusQuery(boolean isThesaurusQuery) Sets this Query to be run as a Thesaurus query if true.
void	setMaxNumResults(int maxNumResults) Sets the maximum number of results to be returned.
void	setQueryType(int type) Sets the query type.
void	setRelevanceCut(int relevanceCut) Sets the relevance cut (results threshold, minimum similarity score) for query results.
void	setSortByDate(boolean doSortByDate) Specifies whether the query results are to be sorted by date.
void	setSortByRelevance(boolean doSortByRelevance) Specifies whether the query results are to be sorted by relevance.
void	setSuggestOptions(boolean useIDs, boolean excludeSuggestDocs) Sets options for a "suggest more" query.
void	setText(String queryText) Sets the query text.
void	setThesaurus(EbiRepositoryDesc thesaurus) Sets up the Thesaurus options for this Query object.
void	setUseAbsWeight(boolean useAbsWeight) Specifies that the relevance scores are to be returned per document as absolute weights rather than percentages.
Document	toXML() Returns an XML representation of the query object.

Field Detail

QUERY_TYPE_TEXT

public static final int QUERY_TYPE_TEXT

Basic text query type.

 // Instantiate a blank query object
 com.sssw.search.api.EbiQuery query = com.sssw.search.factory.EboFactory.getQuery();
 // The query type will be "text"
 query.setQueryType(query.QUERY_TYPE_TEXT);
 query.setText("thriller+psychological");
 

QUERY_TYPE_FUZZY

public static final int QUERY_TYPE_FUZZY

Fuzzy query type. Used for the cases when the user isn't sure of the spelling of the terms.

 // Instantiate a blank query object
 com.sssw.search.api.EbiQuery query = com.sssw.search.factory.EboFactory.getQuery();
 // The query type will be "fuzzy"
 query.setQueryType(query.QUERY_TYPE_FUZZY);
 query.setText("film+noir");
 

QUERY_TYPE_GETALL

public static final int QUERY_TYPE_GETALL

The "get all documents" query type.

QUERY_TYPE_SUGGEST

public static final int QUERY_TYPE_SUGGEST

The "suggest similar documents" query type.

 // Instantiate a blank query object
 com.sssw.search.api.EbiQuery query = com.sssw.search.factory.EboFactory.getQuery();
 // The query type will be "suggest more"
 query.setQueryType(query.QUERY_TYPE_SUGGEST);
 query.setSuggestOptions(false, true);
 query.setText("Arts/Movies/1999/The Matrix+Arts/Movies/1979/Alien");
 

QUERY_TYPE_NAMESEARCH

public static final int QUERY_TYPE_NAMESEARCH

The "name search" query type to search for proper names.

 // Instantiate a blank query object
 com.sssw.search.api.EbiQuery query = com.sssw.search.factory.EboFactory.getQuery();
 // The query type will be "namesearch"
 query.setQueryType(query.QUERY_TYPE_NAMESEARCH);
 query.setText("Jane+Fonda");
 

Method Detail

setQueryType

public void setQueryType(int type)

Sets the query type. By default, QUERY_TYPE_TEXT is used.

Parameters:

type - the query type

See Also:

"the QUERY_TYPE_* constants", EbiQuery.getQueryType()

getQueryType

public int getQueryType()

Returns the query type.

See Also:

EbiQuery.setQueryType(int)

setSuggestOptions

public void setSuggestOptions(boolean useIDs,
                              boolean excludeSuggestDocs)

Sets options for a "suggest more" query. (QUERY_TYPE_SUGGEST). Use this method for suggest queries only.

Parameters:

useIDs - if true, then the document identifiers supplied in the query text are to be treated as document IDs, otherwise as document references

excludeSuggestDocs - if true, then the documents whose identifiers are specified in the query text are to be excluded from the query results

mustUseIDsForSuggest

public boolean mustUseIDsForSuggest()

Returns true if the document identifiers supplied in the query text are to be treated as document IDs. Use this method for suggest queries only.

Returns:

true if the document identifiers supplied in the query text are to be treated as document IDs, false if they are to be treated as document references

See Also:

EbiQuery.setSuggestOptions(boolean, boolean)

mustExcludeSuggestDocs

public boolean mustExcludeSuggestDocs()

Returns true if the documents whose identifiers are specified in the query text are to be excluded from the query results. Use this method for suggest queries only.

Returns:

true if the documents whose identifiers are specified in the query text are to be excluded from the query results

setBatchOptions

public void setBatchOptions(int batchStart,
                            int batchSize)

Sets options for retrieving a batch ("pageful") of query results instead of retrieving all results in a single request.

 query.setText("silk+worm");
 boolean done = false;
 int batchStart = 0;
 int batchSize = 10;
 // While there are unprocessed results
 while (!done) {
     * 	// Set up the batch start and size
     * 	query.setBatchOptions(batchStart, batchSize);
     * 	// Get the next batchful
     * 	Collection results = queryEngine.runQuery(
          		context, query, repositories, true);
     * 	// If no results, we're done
     * 	if (results.isEmpty())
          		done = true;
     * 	// Otherwise
     * 	else {
          		// Process this batchful
          		printResults(results);
          		// This must be the last batch
          		if (results.size() < batchSize)
             			done = true;
          		// Go on to the next batch
          		else
             			batchStart += batchSize;
     * 	}
 }
 

Parameters:

batchStart - start the start of the batch

batchSize - the batch size

See Also:

EbiQuery.getBatchStart(), EbiQuery.getBatchSize()

getBatchStart

public int getBatchStart()

Returns the batch size for batch queries. For example, if 100 documents match the query, a batch would be specified as { 1, 10 } to retrieve the first ten documents, where 1 is the batch start and 10 is the batch size. The parameters would be { 11, 10 } to get the next ten matches, and so on.

Returns:

the batch start

See Also:

EbiQuery.getBatchSize(), EbiQuery.setBatchOptions(int, int)

getBatchSize

public int getBatchSize()

Returns the batch size for batch queries.

Returns:

the batch size

See Also:

EbiQuery.getBatchStart(), EbiQuery.setBatchOptions(int, int)

isBatched

public boolean isBatched()

Returns true if the the query is being run in batch mode. Batch mode is used to return query results over multiple requests.

Returns:

true if the query is being run in the batch mode

setThesaurus

public void setThesaurus(EbiRepositoryDesc thesaurus)

Sets up the Thesaurus options for this Query object. This method must be called if the query is intended to be a Thesaurus query.

 query.setText("inhalation");
 query.setIsThesaurusQuery(true);
 EbiRepositoryDesc thesaurus = com.sssw.search.factory.EboFactory.getRepositoryDesc(
    "141.155.166.181", 52000, 52001, "MyThesaurus");
 query.setThesaurus(thesaurus);
 Collection results = queryEngine.runQuery(
    context, query, repositories, true);
 

Parameters:

thesaurus - the Thesaurus descriptor

See Also:

EbiRepositoryDesc, EbiQuery.getThesaurus(), EbiQuery.setIsThesaurusQuery(boolean), EbiQuery.isThesaurusQuery()

getThesaurus

public EbiRepositoryDesc getThesaurus()

Returns the Thesaurus options set up for this Query object, if any.

Returns:

the Thesaurus descriptor, or null if not set

See Also:

EbiRepositoryDesc, EbiQuery.setThesaurus(EbiRepositoryDesc), EbiQuery.setIsThesaurusQuery(boolean), EbiQuery.isThesaurusQuery()

setIsThesaurusQuery

public void setIsThesaurusQuery(boolean isThesaurusQuery)

Sets this Query to be run as a Thesaurus query if true.

Parameters:

isThesaurusQuery - if true, marks this Query to be run as a Thesaurus query

isThesaurusQuery

public boolean isThesaurusQuery()

Returns true if this Query is marked to run as a thesaurus query.

Returns:

true if this Query is marked to run as a thesaurus query

setText

public void setText(String queryText)

Sets the query text.

Parameters:

queryText - the query text, e.g. "movie+science+fiction"

getText

public String getText()

Returns the query text.

Returns:

the query text

setMaxNumResults

public void setMaxNumResults(int maxNumResults)

Sets the maximum number of results to be returned.

Parameters:

maxNumResults - the maximum number of results to be returned

getMaxNumResults

public int getMaxNumResults()

Returns the maximum number of results to be returned.

Returns:

the maximum number of results to be returned

setRelevanceCut

public void setRelevanceCut(int relevanceCut)

Sets the relevance cut (results threshold, minimum similarity score) for query results.

Parameters:

relevanceCut - the relevance cut

See Also:

EbiQuery.getRelevanceCut()

getRelevanceCut

public int getRelevanceCut()

Returns the relevance cut for query results.

Returns:

the relevance cut

See Also:

EbiQuery.setRelevanceCut(int)

setDateRange

public void setDateRange(Date from,
                         Date to)

Sets the date range (optional).

Parameters:

from - the start of the date range

to - the end of the date range

See Also:

EbiQuery.getDateRangeStart(), EbiQuery.getDateRangeEnd()

getDateRangeStart

public Date getDateRangeStart()

Returns the start of the date range, if one has been specified.

Returns:

the start of the date range

See Also:

EbiQuery.getDateRangeEnd(), EbiQuery.setDateRange(Date, Date)

getDateRangeEnd

public Date getDateRangeEnd()

Returns the end of the date range, if one has been specified.

Returns:

the end of the date range

See Also:

EbiQuery.getDateRangeStart(), EbiQuery.setDateRange(Date, Date)

setGenerateQuickSummary

public void setGenerateQuickSummary(boolean generate)

Specifies that quick summaries are to be generated for each of the query results. Quick summaries are only generated if document contents are stored in the query engine.

Parameters:

generate - if true, do generate the quick summaries

mustGenerateQuickSummary

public boolean mustGenerateQuickSummary()

Returns true if quick summaries are to be generated for each of the query results.

Returns:

true if quick summaries are to be generated for each of the query results

setUseAbsWeight

public void setUseAbsWeight(boolean useAbsWeight)

Specifies that the relevance scores are to be returned per document as absolute weights rather than percentages. By default, percentages are used.

Parameters:

useAbsWeight -

mustUseAbsWeight

public boolean mustUseAbsWeight()

Returns true if relevance scores are to be returned per document as absolute weights rather than percentages.

Returns:

true if relevance scores are to be returned per document as absolute weights rather than percentages

setSortByDate

public void setSortByDate(boolean doSortByDate)

Specifies whether the query results are to be sorted by date.

Parameters:

doSortByDate - if true, the query results are to be sorted by date

mustSortByDate

public boolean mustSortByDate()

Returns true if query results are to be sorted by date.

Returns:

true if the query results are to be sorted by date

setSortByRelevance

public void setSortByRelevance(boolean doSortByRelevance)

Specifies whether the query results are to be sorted by relevance.

Parameters:

doSortByRelevance - if true, the query results are to be sorted by relevance

mustSortByRelevance

public boolean mustSortByRelevance()

Returns true if query results are to be sorted by relevance.

Returns:

true if the query results are to be sorted by relevance

setExclusions

public void setExclusions(String[] exclusions,
                          boolean useAsIDs)

Specifies any exclusions from the query results.

Parameters:

exclusions -

useAsIDs -

See Also:

EbiQuery.mustUseExclusionsAsIDs(), EbiQuery.getExclusions()

getExclusions

public String[] getExclusions()

Returns the list of any document exclusions from the query results.

Returns:

an array of document identifiers (ID's or references, depending on the value set in the setExclusions method)

See Also:

EbiQuery.setExclusions(String[], boolean), EbiQuery.mustUseExclusionsAsIDs()

mustUseExclusionsAsIDs

public boolean mustUseExclusionsAsIDs()

Returns true if any specified exclusions should be treated as document ID's.

Returns:

true if any specified exclusions should be treated as document ID's, false if they should be treated as document references (URL's)

See Also:

EbiQuery.setExclusions(String[], boolean), EbiQuery.getExclusions()

setFieldSpecList

public void setFieldSpecList(String fieldSpecList,
                             String fieldBooleanExpr)

Sets the field specifier list.

Example:

 // Search for documents whose Title is like "Gold Rush"
 // and whose Genre is Comedy
 String fieldSpecList = "fnameTITLE=*Gold Rush*+fnameGenre=*Comedy*"
 String fieldBooleanExpr = "fnameTITLE+AND+fnameGenre";
 query.setFieldSpecList(fieldSpecList, fieldBooleanExpr);
 

Parameters:

fieldSpecList - the field specifier list

fieldBooleanExpr - the field Boolean expression (if more than one field spec given in fieldSpecList, defines a Boolean expression for them)

See Also:

EbiQuery.getFieldSpecList(), EbiQuery.getFieldBooleanExpr()

getFieldSpecList

public String getFieldSpecList()

Returns the field specifier list.

Returns:

the field specifier list

See Also:

EbiQuery.setFieldSpecList(String, String)

getFieldBooleanExpr

public String getFieldBooleanExpr()

Returns the field Boolean expression, if one has been specified.

Returns:

the field Boolean expression

See Also:

EbiQuery.setFieldSpecList(String, String)

selectAll

public void selectAll()

Selects all available document properties to be returned in the query results.

See Also:

EbiQuery.deselectAll(), EbiQuery.allSelected(), EbiQuery.getSelects()

deselectAll

public void deselectAll()

Deselects all the properties that the caller previously selected.

See Also:

EbiQuery.allSelected(), EbiQuery.getSelects(), EbiQuery.selectAll()

allSelected

public boolean allSelected()

Returns true if all document properties have been selected.

Returns:

true if all the document properties are selected

See Also:

EbiQuery.selectAll(), EbiQuery.deselectAll(), EbiQuery.getSelects()

getSelects

public Collection getSelects()

Returns the list of selected document properties.

Returns:

a CollectionString's)

See Also:

EbiQuery.selectAll(), EbiQuery.deselectAll(), EbiQuery.allSelected()

selectAlways

public void selectAlways(String propName)

Specifies that the given property is always to be selected.

Parameters:

propName - the property that is always to be selected

select

public void select(String propName)

Selects a specific property.

Parameters:

propName - the property to select

removeSelect

public boolean removeSelect(String propName)

Removes the specified property from the list of selected properties.

Parameters:

propName - the property name

Returns:

true if successfully removed the property from the list, false if it was not found in the list of selected properties

isSelected

public boolean isSelected(String propName)

Returns true if the specified property is selected.

Parameters:

propName - the property name

Returns:

true if selected, false if not

clear

public void clear()

Clears any information set into the query by the caller.

fromXML

public void fromXML(Node xmlData)

Initializes this query object from XML data.

Parameters:

xmlData - the XML data to use

toXML

public Document toXML()

Returns an XML representation of the query object.

Returns:

an XML representation of the query object