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() Tells whether all the document properties are 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(org.w3c.dom.Node xmlData) Initializes this query object from XML data.
int	getBatchSize() For batch queries, gets the chosen batch size.
int	getBatchStart() For batch queries, gets the chosen batch start.
Date	getDateRangeEnd() Gets the upper bracket (end) of the date range, if specified.
Date	getDateRangeStart() Gets the lower bracket (start) of the date range, if specified.
String[]	getExclusions() Gets the list of any exclusions, i.e.
String	getFieldBooleanExpr() Gets the field Boolean expression, if any
String	getFieldSpecList() Gets the field specifier list.
int	getMaxNumResults() Gets the maximum number of results to be returned.
int	getQueryType() Gets the query type.
int	getRelevanceCut() Gets the relevance cut.
Collection	getSelects() Get the list of selected document properties.
String	getText() Gets the query text.
EbiRepositoryDesc	getThesaurus() Gets the Thesaurus options set up for this Query object, if any.
boolean	isBatched() Tells whether the query is being run in the batch mode, i.e.
boolean	isSelected(String propName) Tells whether the specified property is selected.
boolean	isThesaurusQuery() Tells whether this Query is marked to run as a thesaurus query.
boolean	mustExcludeSuggestDocs() Tells whether the documents whose identifiers are specified in the query text are to be excluded from the query results.
boolean	mustGenerateQuickSummary() Tells whether quick summaries are to be generated per each of the query results.
boolean	mustSortByDate() Tells whether the query results are to be sorted by date.
boolean	mustSortByRelevance() Tells whether the query results are to be sorted by relevance.
boolean	mustUseAbsWeight() Tells whether relevance scores are to be returned per document as absolute weights rather than percentages.
boolean	mustUseExclusionsAsIDs() Tells whether any specified exclusions should be treated as document IDs.
boolean	mustUseIDsForSuggest() Tells whether 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 getting a batch ("pageful") of query results back instead of getting all the results back.
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 per each of the query results.
void	setIsThesaurusQuery(boolean isThesaurusQuery) Marks (or unmarks) this Query to be run as a thesaurus query.
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 (QUERY_TYPE_SUGGEST).
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.
org.w3c.dom.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()

Gets 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()

Tells whether 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()

Tells whether 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 getting a batch ("pageful") of query results back instead of getting all the results back.

 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:

batch - start the start of the batch

batchSize - the batch size

See Also:

EbiQuery.getBatchStart(), EbiQuery.getBatchSize()

getBatchStart

public int getBatchStart()

For batch queries, gets the chosen batch start. E.g. if 100 documents match the query, a batch may be { 1, 10 } - to get the first ten documents, where 1 is the batch start and 10 is the batch size, { 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()

For batch queries, gets the chosen batch size.

Returns:

the batch size

See Also:

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

isBatched

public boolean isBatched()

Tells whether the query is being run in the batch mode, i.e. only a portion of results is being retrieved.

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 this 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", 2000, 2001, "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()

Gets 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)

Marks (or unmarks) this Query to be run as a thesaurus query.

Parameters:

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

isThesaurusQuery

public boolean isThesaurusQuery()

Tells whether 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()

Gets 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()

Gets 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()

Gets the relevance cut.

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()

Gets the lower bracket (start) of the date range, if specified.

Returns:

the start of the date range

See Also:

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

getDateRangeEnd

public Date getDateRangeEnd()

Gets the upper bracket (end) of the date range, if 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 per 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()

Tells whether quick summaries are to be generated per each of the query results.

Returns:

true if quick summaries are to be generated per 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()

Tells whether 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()

Tells whether the 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()

Tells whether the 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()

Gets the list of any exclusions, i.e. documents that must be excluded 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()

Tells whether any specified exclusions should be treated as document IDs.

Returns:

true if any specified exclusions should be treated as document IDs, 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()

Gets the field specifier list.

Returns:

the field specifier list

See Also:

EbiQuery.setFieldSpecList(String, String)

getFieldBooleanExpr

public String getFieldBooleanExpr()

Gets the field Boolean expression, if any

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()

Tells whether all the document properties are selected.

Returns:

true if all the document properties are selected

See Also:

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

getSelects

public Collection getSelects()

Get 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)

Tells whether 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(org.w3c.dom.Node xmlData)

Initializes this query object from XML data.

Parameters:

xmlData - The XML data to use.

toXML

public org.w3c.dom.Document toXML()

Returns an XML representation of the query object.

Returns:

an XML representation of the query object