com.jivesoftware.community
Interface SearchQuery

All Superinterfaces:

JiveObject

public interface SearchQuery
extends JiveObject

Encapsulates a search for message, document or blog post content. Use the factory method jiveContext.getSearchQueryManager().createSearchQuery(criteria) to get a handle on a SearchQuery object. From there, set the properties that you're interested in searching on. For example, to search a community for messages containing "Jive is cool", you would use the following code:

 JiveContext jiveContext = JiveApplication.getContext(authToken);
 SearchQueryManager manager = jiveContext.getSearchQueryManager();
 SearchQueryCriteria criteria = manager.createSearchQueryCriteria("Jive is cool");
 SearchQuery query = manager.createSearchQuery(criteria, new Community[] {community});
 // we could search all result types but for this example we're only going to retrieve
 // message results
 List<SearchQueryResult.ResultType> resultTypes = new java.util.ArrayList<SearchQueryResult.ResultType>();
 resultTypes.add(SearchQueryResult.ResultType.MESSAGE); 
 Iterable<SearchQueryResult> allResults = query.getResults(resultTypes);
 for (SearchQueryResult result: allResults) {
  // display 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/documents/blog posts
 by a particular user, messages/documents/blog posts between a date range, messages in a
 particular thread, etc.


 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 SearchQuery.className with the name of your SearchQuery class.
 Your class must have public constructors which accepts an array of Community objects as an 
 argument.


 If you are using a custom implementation of this interface you should also provide a custom 
 SearchQueryLogger implementation if your custom implementation plans on logging search 
 queries. The default implementation of the SearchQueryLogger interface will only work correctly 
 with the default implementation of this interface. See SearchQueryLoggerFactory for
 details.
 










Method Summary




 boolean
equals(SearchQuery searchQuery)



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



 long[]
getCommunityIDs()



          Returns an array of communityID's denoting the communities that will be searched within.



 int
getResultBlogCount(Blog blog)



          Returns the number of blog posts results in the search that match the given blog.



 JiveIterator<Blog>
getResultBlogs()



          Returns an Iterable of the Blogs that search results are from.



 JiveIterator<Community>
getResultCommunities()



          Returns an Iterable of the Communities that search results are from.



 int
getResultCommunityCount(Community community)



          Returns the number of document results in the search that match the given community.



 int
getResultCount()



          Returns the total number of results of the query for all result types.



 int
getResultCount(java.util.List<SearchQueryResult.ResultType> types)



          Returns the total number of results of the query across the provided list of result types.



 java.lang.Iterable<SearchQueryResult>
getResults()



          Returns the search query results for all result types.



 java.lang.Iterable<SearchQueryResult>
getResults(int startIndex,
           int numResults)



          Returns the results of the query for all result types.



 java.lang.Iterable<SearchQueryResult>
getResults(java.util.List<SearchQueryResult.ResultType> types)



          Returns the search query results across the provided list of result types.



 java.lang.Iterable<SearchQueryResult>
getResults(java.util.List<SearchQueryResult.ResultType> types,
           int startIndex,
           int numResults)



          Returns the results of the query across the provided list of result types.



 SearchQueryCriteria
getSearchQueryCriteria()



          Returns the criteria that will be used to return results.



 User
getUser()



          Returns the user that is executing the search.



 long
logQuery(User user)



          Logs the query for later statistical analysis.


 
Methods inherited from interface com.jivesoftware.community.JiveObject
getID, getObjectType
 





Method Detail



getSearchQueryCriteria
SearchQueryCriteria getSearchQueryCriteria()

Returns the criteria that will be used to return results.






Returns:
the criteria that will be used to return results.





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.





getResultCount
int getResultCount()

Returns the total number of results of the query for all result types.






Returns:
the number of results of the query for all result types.





getResultCount
int getResultCount(java.util.List<SearchQueryResult.ResultType> types)

Returns the total number of results of the query across the provided list of result types.





Parameters:
types - a list of result types to return the search query result for
Returns:
the number of results of the query across the provided list of result types.





getResults
java.lang.Iterable<SearchQueryResult> getResults()

Returns the search query results for all result types.






Returns:
the search query results for all result types.





getResults
java.lang.Iterable<SearchQueryResult> getResults(java.util.List<SearchQueryResult.ResultType> types)

Returns the search query results across the provided list of result types.





Parameters:
types - a list of result types to return search query results for
Returns:
the search query results across the provided list of result types.





getResults
java.lang.Iterable<SearchQueryResult> getResults(int startIndex,
                                                 int numResults)

Returns the results of the query for all result types.
 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 iterable will start at.
numResults - the max number of results that should be returned.
Returns:
the result of the query as an Iterable.





getResults
java.lang.Iterable<SearchQueryResult> getResults(java.util.List<SearchQueryResult.ResultType> types,
                                                 int startIndex,
                                                 int numResults)

Returns the results of the query across the provided list of result types.
 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:
types - a list of result types to return search query results for
startIndex - the index in the results that the iterable will start at.
numResults - the max number of results that should be returned.
Returns:
the result of the query as an Iterable.





getResultBlogCount
int getResultBlogCount(Blog blog)

Returns the number of blog posts results in the search that match the given blog.





Parameters:
blog - the blog to count the blog post search results for
Returns:
the total number of results that match the given blog





getResultBlogs
JiveIterator<Blog> getResultBlogs()

Returns an Iterable of the Blogs that search results are from. For example, a search
 of the entire community (of ten blogs) might return twenty-five posts from two
 different blogs. This method will return those two blogs. This feature is
 useful for allowing users to narrow their search results, such as "show me all results
 in this blog".






Returns:
the blogs that search results are from.





getResultCommunityCount
int getResultCommunityCount(Community community)

Returns the number of document results in the search that match the given community.





Parameters:
community - the Community to count the document search results for
Returns:
the total number of document results that are in the given community





getResultCommunities
JiveIterator<Community> getResultCommunities()

Returns an Iterable of the Communities that search results are from. For example, a search
 of the entire community (of ten communities) might return twenty-five documents from two
 different communities. This method will return those two communities. This feature is
 useful for allowing users to narrow their search results, such as "show me all results
 in this community".






Returns:
the communities that search results are from.





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 the Lite and Professional editions.





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





getCommunityIDs
long[] getCommunityIDs()

Returns an array of communityID's denoting the communities that will be searched within. This
 may be null if there are no community restrictions.






Returns:
an array of communityID's denoting the communities that will be searched within or null
      if there are no community restrictions





equals
boolean equals(SearchQuery searchQuery)

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





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