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<com.jivesoftware.community.objecttype.JiveObjectType> resultTypes = new java.util.ArrayList<com.jivesoftware.community.objecttype.JiveObjectType>();
 resultTypes.add(com.jivesoftware.community.objecttype.JiveObjectType.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. 
 










Method Summary




 boolean
equals(SearchQuery searchQuery)



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



 int
getResultCount()



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



 int
getResultCount(JiveObject jiveObject)



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



 int
getResultCount(List<Integer> objectTypes)



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



 Iterable<SearchQueryResult>
getResults()



          Returns the search query results for all result types.



 Iterable<SearchQueryResult>
getResults(int startIndex,
           int numResults)



          Returns the results of the query for all result types.



 Iterable<SearchQueryResult>
getResults(JiveObject jiveObject)



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



 Iterable<SearchQueryResult>
getResults(List<Integer> objectTypes)



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



 Iterable<SearchQueryResult>
getResults(List<Integer> objectTypes,
           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.



 long
getUserID()



          Returns the user id that is executing the search.



 Map<IndexField,String>
highlightResult(SearchQueryResult searchQueryResult,
                String preTag,
                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
reset()



          Invoking this method will reset this object to a state prior to any query executions.


 
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.





getUserID
long getUserID()

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






Returns:
the user id 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(List<Integer> objectTypes)

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





Parameters:
objectTypes - 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
Iterable<SearchQueryResult> getResults()

Returns the search query results for all result types.






Returns:
the search query results for all result types.





getResults
Iterable<SearchQueryResult> getResults(List<Integer> objectTypes)

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





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





getResults
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
Iterable<SearchQueryResult> getResults(List<Integer> objectTypes,
                                       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:
objectTypes - 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.





getResultCount
int getResultCount(JiveObject jiveObject)

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





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





getResults
Iterable<SearchQueryResult> getResults(JiveObject jiveObject)

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





Parameters:
jiveObject - the jiveObject to get the search results for
Returns:
the blogs 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.





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.





highlightResult
Map<IndexField,String> highlightResult(SearchQueryResult searchQueryResult,
                                       String preTag,
                                       String postTag)

Returns a title and summary with search words highlighted appropriate to the search
 query string.





Parameters:
searchQueryResult - the search query result 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.





reset
void reset()

Invoking this method will reset this object to a state prior to any query executions.