com.jivesoftware.forum.database
Class DbQuery

java.lang.Object
  com.jivesoftware.forum.database.DbQuery

All Implemented Interfaces:

Query, Cacheable, java.io.Serializable

public class DbQuery
extends java.lang.Object
implements Query, Cacheable

Database implementation of the Query interface using Lucene. The maximum number of search results can be set using the Jive property search.maxResultsSize. The default value is 1500.

See Also:

Serialized Form

Field Summary

protected java.util.Date	afterDate
protected java.util.Date	beforeDate
protected long	filteredUserID
protected long[]	forumIDs
protected static int	MAX_RESULTS_SIZE The maximum number of results to return with a search.
protected long	threadID

Fields inherited from interface com.jivesoftware.forum.Query

ASCENDING, DATE, DESCENDING, RATING, RELEVANCE, SUBJECT

Constructor Summary

DbQuery(Forum[] forums)

DbQuery(long id)
Load an existing query.

Method Summary

boolean	equals(java.lang.Object o)
boolean	equals(Query query) Return true if the query is equal to the current query, false otherwise.
static java.lang.String	escapeBadCharacters(java.lang.String queryString) This method escapes characters that would otherwise potentially cause a query to be malformed.
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.
int	getCachedSize() Returns the approximate size of the Object in bytes.
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.
Forum[]	getForums()
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.
java.util.Date	getSearchDate()
int	getSearchDuration()
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.
long	getUserID()
int	hashCode()
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.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_RESULTS_SIZE

protected static final int MAX_RESULTS_SIZE

The maximum number of results to return with a search.

filteredUserID

protected long filteredUserID

forumIDs

protected long[] forumIDs

threadID

protected long threadID

beforeDate

protected java.util.Date beforeDate

afterDate

protected java.util.Date afterDate

Constructor Detail

DbQuery

public DbQuery(Forum[] forums)

DbQuery

public DbQuery(long id)
        throws NotFoundException

Load an existing query.

Parameters:

id - the id of the query to load

Throws:

NotFoundException - if the Query cannot be retrieved from the database

Method Detail

getID

public long getID()

Description copied from interface: Query

Retrieve the unique identifier for the query.

Specified by:

getID in interface Query

Returns:

the unique identifier for the query.

getUserID

public long getUserID()

getUser

public User getUser()

Description copied from interface: Query

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

Specified by:

getUser in interface Query

Returns:

the user that is executing the search.

getObjectType

public int getObjectType()

Description copied from interface: Query

Return the object type of the query.

Specified by:

getObjectType in interface Query

Returns:

the object type of the query.

getSearchDate

public java.util.Date getSearchDate()

getSearchDuration

public int getSearchDuration()

getForums

public Forum[] getForums()

setQueryString

public void setQueryString(java.lang.String queryString)

Description copied from interface: Query

Sets the query string for the Query object.

Specified by:

setQueryString in interface Query

Parameters:

queryString - a new query string.

getQueryString

public java.lang.String getQueryString()

Description copied from interface: Query

Returns the query string for the Query object. If the query string has not been set, this method will return null.

Specified by:

getQueryString in interface Query

Returns:

the Query query string.

setBeforeDate

public void setBeforeDate(java.util.Date beforeDate)

Description copied from interface: Query

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.

Specified by:

setBeforeDate in interface Query

Parameters:

beforeDate - an upper date boundary for search results.

getBeforeDate

public java.util.Date getBeforeDate()

Description copied from interface: Query

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.

Specified by:

getBeforeDate in interface Query

Returns:

the upder date boundary for search results.

setAfterDate

public void setAfterDate(java.util.Date afterDate)

Description copied from interface: Query

Sets the earliest date for search results. For example, the "after date" can be used to search for messages modified within the last week.

Specified by:

setAfterDate in interface Query

Parameters:

afterDate - a lower date boundary for search results.

getAfterDate

public java.util.Date getAfterDate()

Description copied from interface: Query

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.

Specified by:

getAfterDate in interface Query

Returns:

the lower date boundary for search results.

getForumIDs

public long[] getForumIDs()

Description copied from interface: Query

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

Specified by:

getForumIDs in interface Query

Returns:

an array of forumID's denoting the forums that will be searched within.

getFilteredUser

public User getFilteredUser()

Description copied from interface: Query

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.

Specified by:

getFilteredUser in interface Query

Returns:

the message that results are restricted to.

filterOnUser

public void filterOnUser(User user)

Description copied from interface: Query

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.

Specified by:

filterOnUser in interface Query

Parameters:

user - a User to restrict query results to.

See Also:

ResultFilter

getFilteredThread

public ForumThread getFilteredThread()

Description copied from interface: Query

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.

Specified by:

getFilteredThread in interface Query

Returns:

the thread that results are restricted to.

filterOnThread

public void filterOnThread(ForumThread thread)

Description copied from interface: Query

Restricts the querty results to messages posted in a specified thread.

Specified by:

filterOnThread in interface Query

Parameters:

thread - the ForumThread to restrict query results to.

getSortField

public int getSortField()

Description copied from interface: Query

Returns the currently selected sort field. Default is Query.RELEVANCE.

Specified by:

getSortField in interface Query

Returns:

current sort.

setSortField

public void setSortField(int sortField)

Description copied from interface: Query

Sets the sort field to use. Default is Query.RELEVANCE.

Specified by:

setSortField in interface Query

Parameters:

sortField - the field that will be used for sorting.

getSortOrder

public int getSortOrder()

Description copied from interface: Query

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.

Specified by:

getSortOrder in interface Query

Returns:

the sort order.

setSortOrder

public void setSortOrder(int sortOrder)

Description copied from interface: Query

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.

Specified by:

setSortOrder in interface Query

Parameters:

sortOrder - the order that results will be sorted in.

getResultCount

public int getResultCount()

Description copied from interface: Query

Returns the total number of results of the query.

Specified by:

getResultCount in interface Query

Returns:

the number of results of the query.

getResultByThreadCount

public int getResultByThreadCount()

Description copied from interface: Query

Returns the total number of threads that contain query results.

Specified by:

getResultByThreadCount in interface Query

Returns:

the number of threads that contain query results.

getResults

public java.util.Iterator getResults()

Description copied from interface: Query

Returns the results of the query as an Iterator of QueryResult objects.

Specified by:

getResults in interface Query

Returns:

the result of the query as an Iterator.

See Also:

QueryResult

getResults

public java.util.Iterator getResults(int startIndex,
                                     int numResults)

Description copied from interface: Query

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.

Specified by:

getResults in interface Query

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

public java.util.Iterator getResultsByThread()

Description copied from interface: Query

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.

Specified by:

getResultsByThread in interface Query

Returns:

the result of the query as an Iterator.

getResultsByThread

public java.util.Iterator getResultsByThread(int startIndex,
                                             int numResults)

Description copied from interface: Query

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.

Specified by:

getResultsByThread in interface Query

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.

getResultForums

public java.util.Iterator getResultForums()

Description copied from interface: Query

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".

Specified by:

getResultForums in interface Query

Returns:

the forums that search results are from.

getResultForumCount

public int getResultForumCount(Forum forum)

Description copied from interface: Query

Returns the number of results in the search that match the given forum.

Specified by:

getResultForumCount in interface Query

Returns:

the total number of results that match the given forum ID

getResultForumCountByThread

public int getResultForumCountByThread(Forum forum)

Description copied from interface: Query

Returns the number of results in the search that match the given forum where search results are grouped by thread.

Specified by:

getResultForumCountByThread in interface Query

Returns:

the total number of results that match the given forum ID

highlightResult

public java.lang.String[] highlightResult(QueryResult result,
                                          java.lang.String preTag,
                                          java.lang.String postTag)

Description copied from interface: Query

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 Query.getResults() or Query.getResults(int, int).

Specified by:

highlightResult in interface Query

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.

logQuery

public long logQuery(User user)

Description copied from interface: Query

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.

Specified by:

logQuery in interface Query

Parameters:

user - the user performing the query, or null if a guest is performing the search.

Returns:

a searchID as a long.

logSearchClick

public void logSearchClick(long searchID,
                           long messageID)

Description copied from interface: Query

Logs a search result clickthrough.

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

Specified by:

logSearchClick in interface Query

Parameters:

searchID - the searchID of the search associated with the clickthrough.

messageID - the messageID of the search result that was clicked

getCachedSize

public int getCachedSize()

Description copied from interface: Cacheable

Returns the approximate size of the Object in bytes. The size should be considered to be a best estimate of how much memory the Object occupies and may be based on empirical trials or dynamic calculations.

Specified by:

getCachedSize in interface Cacheable

Returns:

the size of the Object in bytes.

equals

public boolean equals(Query query)

Description copied from interface: Query

Return true if the query is equal to the current query, false otherwise.

Specified by:

equals in interface Query

Parameters:

query - the query to compare to the current query

Returns:

true if the query is equal to the current query, false otherwise.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

escapeBadCharacters

public static java.lang.String escapeBadCharacters(java.lang.String queryString)

This method escapes characters that would otherwise potentially cause a query to be malformed. Cuurrently the : and " characters are escaped (the colon characters is used by the query parser to denote fields to search within, the " character is used for phrases).
Note that only single occurrances of the " character is escaped. That means that a query that has unbalanced quotes such as 20" "apple cinema display" would still cause the query parser to fail and the query to return no results. TODO - find a method to determine which quotes are part of a phrase and which are not.