com.jivesoftware.community.search.opensearch
Interface SearchEngine

All Superinterfaces:

JiveObject

public interface SearchEngine
extends JiveObject

A SearchEngine is an external source that can be searched. SearchResults may or may not be parseable by our client (in a computer readable format such as XML in the form of Atom or RSS).

See http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document for the full OpenSearch descriptor specification. The descriptor (if one exists) can be found by calling the getDescriptorURL(). NOTE: this class is NOT a complete representation of what may be found on the descriptor file.

See Also:

SearchResult, SearchEngineManager

Method Summary

java.lang.String	getDescription() Get a description of the search engine.
java.lang.String	getDescriptorURL() Get the URL of the XML opensearch descriptor file.
java.lang.String	getExternalSearchableURL(java.lang.String searchTerms) Get the externral search URL with the {searchTerms} token substitued by the argument.
java.lang.String	getExternalSearchURL() Get an OpenSearch compliant URL that can be queried against.
java.lang.String	getIconURL() Get the URL of an icon described in the descriptor file.
int	getMaxResultCount() The maximum number of results you want returned from #performSearch.
java.lang.String	getQueryTestTerm() Get the test term that is used for performing the test query.
java.lang.String	getSearchableURL(java.lang.String searchTerms) Get the search URL with the {searchTerms} token substitued by the argument.
java.lang.String	getSearchHttpMethod() Get the Http method (i.e.
java.lang.String	getSearchResultContentType() Get the content type (i.e. text/xml) of search results.
java.lang.String	getSearchURL() Get an OpenSearch compliant URL that can be queried against.
java.lang.String	getShortName() Get the short name of the search engine.
boolean	isAuthenticated() Check whether or not the search result feed requires HTTP authentication.
boolean	isEnabled() Get whether or not this engine will appear in the view.
boolean	isQueryResultParseable() Check whether or not the search result content type is machine parseable (an XML content type such as would be used for RSS or Atom content) or not (a nonstrict-XML type such as HTML content).
java.util.Collection<SearchResult>	performSearch(java.lang.String searchTerms) Performs a query agaist the search URL with the specified search terms.
boolean	performTestQuery() Performs a test query using the query test term.
void	setEnabled(boolean enabled) Set whether or not this engine will appear in the view.
void	setMaxResultCount(int maxResultCount) The maximum number of results you want returned from #performSearch.
void	setPassword(java.lang.String password) Set a password for authenticated search feeds.
void	setQueryTestTerm(java.lang.String term) Set the test term that is used for performing the test query.
void	setUsername(java.lang.String username) Set a username for authenticated search feeds.

Methods inherited from interface com.jivesoftware.community.JiveObject

getID, getObjectType

Method Detail

getShortName

java.lang.String getShortName()

Get the short name of the search engine.

Returns:

the short name of the search engine.

getDescription

java.lang.String getDescription()

Get a description of the search engine.

Returns:

a description of the search engine.

getDescriptorURL

java.lang.String getDescriptorURL()

Get the URL of the XML opensearch descriptor file.

Returns:

the URL of the XML opensearch descriptor file.

getIconURL

java.lang.String getIconURL()

Get the URL of an icon described in the descriptor file.

Returns:

the URL of an icon described in the descriptor file.

getSearchResultContentType

java.lang.String getSearchResultContentType()

Get the content type (i.e. text/xml) of search results.

Returns:

the content type (i.e. text/xml) of search results.

getSearchHttpMethod

java.lang.String getSearchHttpMethod()

Get the Http method (i.e. GET, POST) that is expected to be used in the call to the search URL.

Returns:

an HTTP method such as GET or POST.

getSearchURL

java.lang.String getSearchURL()

Get an OpenSearch compliant URL that can be queried against. This URL will contain certain tokens such as {searchTerms} that are listed in the OpenSearch specification. Tokens can also be system-specific as well.

Returns:

the Search URL.

getExternalSearchURL

java.lang.String getExternalSearchURL()

Get an OpenSearch compliant URL that can be queried against. This URL will contain certain tokens such as {searchTerms} that are listed in the OpenSearch specification. Tokens can also be system-specific as well. NOTE: this URL will always return non-parseable (HTML) results.

Returns:

the external Search URL.

isQueryResultParseable

boolean isQueryResultParseable()

Check whether or not the search result content type is machine parseable (an XML content type such as would be used for RSS or Atom content) or not (a nonstrict-XML type such as HTML content).

Returns:

true, if the results can be parsed, false otherwise.

isAuthenticated

boolean isAuthenticated()

Check whether or not the search result feed requires HTTP authentication.

Returns:

true, if the feed requires authentication, false otherwise.

getSearchableURL

java.lang.String getSearchableURL(java.lang.String searchTerms)

Get the search URL with the {searchTerms} token substitued by the argument. Other tokens are currently set to default values. If the query results are not parseable (#isQueryResultParseable), this returns the same result as #getExternalSearchableURL.

Parameters:

searchTerms - A search term to use for token substitution.

Returns:

a String URL which will return query results.

getExternalSearchableURL

java.lang.String getExternalSearchableURL(java.lang.String searchTerms)

Get the externral search URL with the {searchTerms} token substitued by the argument. Other tokens are currently set to default values. This will always return an HTML result.

Parameters:

searchTerms - A search term to use for token substitution.

Returns:

a String URL which will return query results.

setUsername

void setUsername(java.lang.String username)

Set a username for authenticated search feeds.

Parameters:

username - a username.

setPassword

void setPassword(java.lang.String password)

Set a password for authenticated search feeds.

Parameters:

password - a username.

performTestQuery

boolean performTestQuery()

Performs a test query using the query test term.

Returns:

true if the feed returns results, false otherwise. NOTE: if an authenticated search feed cannot authenticate (due to lack of credentials or otherwise), this will return false.

performSearch

java.util.Collection<SearchResult> performSearch(java.lang.String searchTerms)

Performs a query agaist the search URL with the specified search terms.

Parameters:

searchTerms - a term or terms to query against.

Returns:

a Collection of SearchResult objects.

getQueryTestTerm

java.lang.String getQueryTestTerm()

Get the test term that is used for performing the test query.

Returns:

a search term.

setQueryTestTerm

void setQueryTestTerm(java.lang.String term)

Set the test term that is used for performing the test query.

Parameters:

term - a search term.

setEnabled

void setEnabled(boolean enabled)

Set whether or not this engine will appear in the view. This is useful if the downstream system will be offline.

Parameters:

enabled - Whether or not the search engine is enabled.

setMaxResultCount

void setMaxResultCount(int maxResultCount)

The maximum number of results you want returned from #performSearch.

Parameters:

maxResultCount - A positive int.

getMaxResultCount

int getMaxResultCount()

The maximum number of results you want returned from #performSearch.

Returns:

A positive int.

isEnabled

boolean isEnabled()

Get whether or not this engine will appear in the view.

Returns:

true if the engine is enabled, false otherwise.