Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum
Interface Query

All Known Implementing Classes:
DbQuery, QueryProxy

public interface Query

Encapsulates a search for content in a forum. Use the factory method forum.createQuery() to get a handle on a Query object. From there, set the properties that you're interested in searching on. For example, to search a forum for "Jive is cool", you would use the following code:

 Query query = forum.createQuery();
 query.setQueryString("Jive is cool");
 Iterator iter = query.results();
 while (iter.hasNext()) {
     ForumMessage message = (ForumMessage)iter.nextElement();
     //print results...
 }
 

All search properties are optional. You can mix and match them depending on what kind of query you'd like to perform.

You can also use the filter methods to restrict searches to messages from a particular user, messages between a date range, or messages in a particular thread.

Instructions for those that wish to implement this interface to provide a custom implementation appear in red. If you wish to use a custom implementation, you must set the Jive property Query.className with the name of your Query class. Your class must have a public constructor which accepts an array of Forum objects as an argument.

If you are using Jive Silver/Gold and are using a custom implementation of this interface you should also provide a custom QueryLogger implementation if your custom implementation plans on logging search queries as the default implementation of the QueryLogger interface will only work correctly with the default implementation of this interface. See QueryLoggerFactory for details.

See Also:
Forum.createQuery(), ForumFactory.createQuery()

Field Summary
static int ASCENDING
          Ascending sort (ie 3, 4, 5...).
static int DATE
          Sort by date
static int DESCENDING
          Descending sort (ie 3, 2, 1...).
static int RATING
          Sort by rating
static int RELEVANCE
          Sort by relevance
static int SUBJECT
          Sort by message subject
 
Method Summary
 boolean equals(Query query)
          Return true if the query is equal to the current query, false otherwise.
 void filterOnThread(ForumThread thread)
          Restricts the querty results to messages posted in a specified thread.
 void filterOnUser(User user)
          Restricts the query results to messages posted by a specified user.
 java.util.Date getAfterDate()
          Returns the earliest date for search results.
 java.util.Date getBeforeDate()
          Returns the latest date for search results.
 ForumThread getFilteredThread()
          Returns the thread that query results are restricted to.
 User getFilteredUser()
          Returns the user that query results are restricted to.
 long[] getForumIDs()
          Returns an array of forumID's denoting the forums that will be searched within.
 long getID()
          Retrieve the unique identifier for the query.
 int getObjectType()
          Return the object type of the query.
 java.lang.String getQueryString()
          Returns the query string for the Query object.
 int getResultByThreadCount()
          Returns the total number of threads that contain query results.
 int getResultCount()
          Returns the total number of results of the query.
 int getResultForumCount(Forum forum)
          Returns the number of results in the search that match the given forum.
 int getResultForumCountByThread(Forum forum)
          Returns the number of results in the search that match the given forum where search results are grouped by thread.
 java.util.Iterator getResultForums()
          Returns an Iterator of the Forums that search results are from.
 java.util.Iterator getResults()
          Returns the results of the query as an Iterator of QueryResult objects.
 java.util.Iterator getResults(int startIndex, int numResults)
          Returns the results of the Query as an Iterator of QueryResult objects.
 java.util.Iterator getResultsByThread()
          Returns the results of the Query as an Iterator of QueryResult objects.
 java.util.Iterator getResultsByThread(int startIndex, int numResults)
          Returns the results of the Query as an Iterator of QueryResult objects.
 int getSortField()
          Returns the currently selected sort field.
 int getSortOrder()
          Returns the sort order, which will be Query.ASCENDING for ascending sorting, or Query.DESCENDING for descending sorting.
 User getUser()
          Returns the user that is executing the search.
 java.lang.String[] highlightResult(QueryResult result, java.lang.String preTag, java.lang.String postTag)
          Returns a title and summary with search words highlighted appropriate to the search query string.
 long logQuery(User user)
          Logs the query for later statistical analysis.
 void logSearchClick(long searchID, long messageID)
          Logs a search result clickthrough.
 void setAfterDate(java.util.Date afterDate)
          Sets the earliest date for search results.
 void setBeforeDate(java.util.Date beforeDate)
          Sets the latest date for search results.
 void setQueryString(java.lang.String queryString)
          Sets the query string for the Query object.
 void setSortField(int sortField)
          Sets the sort field to use.
 void setSortOrder(int sortOrder)
          Sets the sort type.
 

Field Detail

RELEVANCE

static final int RELEVANCE
Sort by relevance

See Also:
Constant Field Values

RATING

static final int RATING
Sort by rating

See Also:
Constant Field Values

DATE

static final int DATE
Sort by date

See Also:
Constant Field Values

SUBJECT

static final int SUBJECT
Sort by message subject

Since:
4.0
See Also:
Constant Field Values

DESCENDING

static final int DESCENDING
Descending sort (ie 3, 2, 1...).

See Also:
Constant Field Values

ASCENDING

static final int ASCENDING
Ascending sort (ie 3, 4, 5...).

See Also:
Constant Field Values
Method Detail

getID

long getID()
Retrieve the unique identifier for the query.

Returns:
the unique identifier for the query.

getObjectType

int getObjectType()
Return the object type of the query.

Returns:
the object type of the query.

getQueryString

java.lang.String getQueryString()
Returns the query string for the Query object. If the query string has not been set, this method will return null.

Returns:
the Query query string.

setQueryString

void setQueryString(java.lang.String queryString)
Sets the query string for the Query object.

Parameters:
queryString - a new query string.

getBeforeDate

java.util.Date getBeforeDate()
Returns the latest date for search results. For example, the "before date" can be used to search for messages modified more than 1 month ago.

If the "before date" has not been set, this method will return null.

Returns:
the upder date boundary for search results.

setBeforeDate

void setBeforeDate(java.util.Date beforeDate)
Sets the latest date for search results. For example, the "before date" can be used to search for messages modified more than 1 month ago.

Parameters:
beforeDate - an upper date boundary for search results.

getAfterDate

java.util.Date getAfterDate()
Returns the earliest date for search results. For example, the "after date" can be used to search for messages modified within the last week.

If the "after date" has not been set, this method will return null.

Returns:
the lower date boundary for search results.

setAfterDate

void setAfterDate(java.util.Date afterDate)
Sets the earliest date for search results. For example, the "after date" can be used to search for messages modified within the last week.

Parameters:
afterDate - a lower date boundary for search results.

getForumIDs

long[] getForumIDs()
Returns an array of forumID's denoting the forums that will be searched within.

Returns:
an array of forumID's denoting the forums that will be searched within.
Since:
4.0.1

getUser

User getUser()
Returns the user that is executing the search. If the search is being performed by an anonymous user the this method will return null.

Returns:
the user that is executing the search.
Since:
4.0.1

getFilteredUser

User getFilteredUser()
Returns the user that query results are restricted to. If the query is not restricted to messages posted by a certain user, this method will return null.

Returns:
the message that results are restricted to.

filterOnUser

void filterOnUser(User user)
Restricts the query results to messages posted by a specified user. Note: this method is not intended to show all messages posted by a user. Rather, it lets you filter out search results; for example, all messages matching the query "Jive rocks", but filtering out all results that aren't posted by some particular user. If you just want to see all messages posted by a user regardless of their actual content, use the ResultFilter class for a particular forum, or the getUserMessages method for a user's messages among all forums.

Parameters:
user - a User to restrict query results to.
See Also:
ResultFilter

getFilteredThread

ForumThread getFilteredThread()
Returns the thread that query results are restricted to. If the query is not restricted to messages in a certain thread, this method will return null.

Returns:
the thread that results are restricted to.

filterOnThread

void filterOnThread(ForumThread thread)
Restricts the querty results to messages posted in a specified thread.

Parameters:
thread - the ForumThread to restrict query results to.

getSortField

int getSortField()
Returns the currently selected sort field. Default is Query.RELEVANCE.

Returns:
current sort.

setSortField

void setSortField(int sortField)
Sets the sort field to use. Default is Query.RELEVANCE.

Parameters:
sortField - the field that will be used for sorting.

getSortOrder

int getSortOrder()
Returns the sort order, which will be Query.ASCENDING for ascending sorting, or Query.DESCENDING for descending sorting. Descending sorting is: 3, 2, 1, etc. Ascending sorting is 1, 2, 3, etc.

Returns:
the sort order.

setSortOrder

void setSortOrder(int sortOrder)
Sets the sort type. Valid arguments are Query.ASCENDING for ascending sorting or Query.DESCENDING for descending sorting. Descending sorting is: 3, 2, 1, etc. Ascending sorting is 1, 2, 3, etc.

Parameters:
sortOrder - the order that results will be sorted in.

getResultCount

int getResultCount()
Returns the total number of results of the query.

Returns:
the number of results of the query.

getResults

java.util.Iterator getResults()
Returns the results of the query as an Iterator of QueryResult objects.

Returns:
the result of the query as an Iterator.
See Also:
QueryResult

getResults

java.util.Iterator getResults(int startIndex,
                              int numResults)
Returns the results of the Query as an Iterator of QueryResult objects. The startIndex and numResults paramaters are used to look at a certain range of the results. For example, the first twenty results, the second twenty results, etc. This is useful for user interface with multiple pages of results.

If startIndex or numResults does not fall within the range of results, the number of messages returned may be smaller than expected. For example, suppose a query has a total of 17 results. If startIndex is 0 and numResults is 25, only 17 results can be returned.

Parameters:
startIndex - the index in the results that the iterator will start at.
numResults - the max number of results that should be returned.
Returns:
the result of the query as an Iterator.
See Also:
QueryResult

getResultsByThread

java.util.Iterator getResultsByThread()
Returns the results of the Query as an Iterator of QueryResult objects. This iterator will only include a single result (the most relevant hit) for every thread.

Returns:
the result of the query as an Iterator.

getResultsByThread

java.util.Iterator getResultsByThread(int startIndex,
                                      int numResults)
Returns the results of the Query as an Iterator of QueryResult objects. This iterator will only include a single result (the most relevant hit) for every thread. The startIndex and numResults paramaters are used to look at a certain range of the results. For example, the first twenty results, the second twenty results, etc. This is useful for user interface with multiple pages of results.

If startIndex or numResults does not fall within the range of results, the number of messages returned may be smaller than expected. For example, suppose a query has a total of 17 results. If startIndex is 0 and numResults is 25, only 17 results can be returned.

Parameters:
startIndex - the index in the results that the iterator will start at.
numResults - the maximum number of results that should be returned.
Returns:
the result of the query as an Iterator.

getResultByThreadCount

int getResultByThreadCount()
Returns the total number of threads that contain query results.

Returns:
the number of threads that contain query results.

getResultForums

java.util.Iterator getResultForums()
Returns an Iterator of the Forums that search results are from. For example, a search of the entire community (of ten forums) might return twenty-five messages from two different forums. This method will return those two forums. This feature is useful for allowing users to narrow their search results, such as "show me all results in this forum".

Returns:
the forums that search results are from.

getResultForumCount

int getResultForumCount(Forum forum)
Returns the number of results in the search that match the given forum.

Parameters:
forum -
Returns:
the total number of results that match the given forum ID

getResultForumCountByThread

int getResultForumCountByThread(Forum forum)
Returns the number of results in the search that match the given forum where search results are grouped by thread.

Parameters:
forum -
Returns:
the total number of results that match the given forum ID

highlightResult

java.lang.String[] highlightResult(QueryResult result,
                                   java.lang.String preTag,
                                   java.lang.String postTag)
Returns a title and summary with search words highlighted appropriate to the search query string. This method can only be called after a call to getResults() or getResults(int, int).

Parameters:
result - the QueryResult to highlight
preTag - a tag to be used to mark the beginning of highlighted text eg <B%gt;
postTag - a tag to be used to mark the beginning of highlighted text eg </B%gt;
Returns:
an array of highlighted text with the title being the first element and a summary of the main text as the second element.
Since:
4.0

logQuery

long logQuery(User user)
Logs the query for later statistical analysis. This method must only be called immediately after the first call to getResults() or getResults(..) for a given query. If the query string is changed or the query parameters are changed in any way then it qualifies as a new query and thus this method should be called again (but only once!).

Note: This method is a noop in Jive Forums Lite and Professional.

Parameters:
user - the user performing the query, or null if a guest is performing the search.
Returns:
a searchID as a long.

logSearchClick

void logSearchClick(long searchID,
                    long messageID)
Logs a search result clickthrough.

Note: This method is a noop in Jive Forums Lite and Professional.

Parameters:
searchID - the searchID of the search associated with the clickthrough.
messageID - the messageID of the search result that was clicked

equals

boolean equals(Query query)
Return true if the query is equal to the current query, false otherwise.

Parameters:
query - the query to compare to the current query
Returns:
true if the query is equal to the current query, false otherwise.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.