Jive Forums API (5.5.20.2-oracle) Core Javadocs

com.jivesoftware.forum
Class ResultFilter

java.lang.Object
  extended by com.jivesoftware.forum.ResultFilter
Direct Known Subclasses:
TagResultFilter

public class ResultFilter
extends java.lang.Object

Filters and sorts lists of threads and messages. This allows for a very rich set of possible queries that can be run on forum data. Some examples are: "Show all messages posted in the forum during the last year by a certain user" or "Show all threads in the forum, sorted by their modification date".

The class also supports pagination of results with the setStartIndex(int) and setNumResults(int) methods. If the start index is not set, it will begin at index 0 (the start of results). If the number of results is not set, it will be unbounded and return as many results as available.

By default, result filters will obey the moderation rules as they are set for each forum. You can override this behavior by setting a moderation range.

Factory methods to create common queries are provided for convenience.

See Also:
Forum.getThreads(ResultFilter), Forum.getMessages(ResultFilter), ForumThread.getMessages(ResultFilter)

Field Summary
static int AND_MODE
          'AND' mode.
static int ASCENDING
          Ascending sort (ie 3, 4, 5...).
static int CONTAINS_MATCH
          Contains match.
static int DESCENDING
          Descending sort (ie 3, 2, 1...).
static int EXACT_MATCH
          Exact match.
static int NULL_INT
          An integer value that represents NULL.
static int OR_MODE
          'OR' mode;
 
Constructor Summary
ResultFilter()
           
 
Method Summary
 void addProperty(java.lang.String name, java.lang.String value)
          Adds a property to the list of properties that will be filtered on.
 void addResolutionState(com.jivesoftware.forum.Question.State resolutionState)
          Adds a resolution state to the set of states that will be included in filtered results.
 void addTag(ContentTag tag)
          Adds a ContentTag to the list of tags to filter on.
 void clearResolutionStates()
          Removes all resolution states from the set of states that will be included in filtered results.
 java.lang.Object clone()
          Clones a ResultFilter
static ResultFilter createDefaultContentFilter()
          Creates a default ResultFilter: no filtering with results sorted on the modification date.
static ResultFilter createDefaultForumFilter()
          Creates a default forum ResultFilter: no filtering with results sorted on the category index value.
static ResultFilter createDefaultMessageFilter()
          Creates a default message ResultFilter: no filtering with results sorted on the message creation date in ascending order.
static ResultFilter createDefaultThreadFilter()
          Creates a default thread ResultFilter: no filtering with results sorted on the thread modification date.
static ResultFilter createDefaultUserMessagesFilter()
          Creates a default user messages ResultFilter: no filtering with results sorted on the message creation date descending (newest messages appear first).
 boolean equals(java.lang.Object o)
           
 java.util.Date getCreationDateRangeMax()
          Returns a date that represents the upper boundry for messages or threads to be selected by the result filter.
 java.util.Date getCreationDateRangeMin()
          Returns the creation date that represents the lower boundary for messages or threads to be filtered on.
 int getModerationRangeMax()
          Returns the moderation value that represents the upper bound for messages or threads to be selected by the result filter.
 int getModerationRangeMin()
          Returns the moderation value that represents the lower boundry for messages or threads to be selected by the result filter.
 java.util.Date getModificationDateRangeMax()
          Returns a date that represents the upper boundry for messages or threads to be selected by the result filter.
 java.util.Date getModificationDateRangeMin()
          Returns a date that represents the lower boundary for messages or threads to be selected by the result filter.
 int getNumResults()
          Returns the max number of results that should be returned.
 int getPropertyCount()
          Returns the number of properties that results will be filtered on.
 int getPropertyMatchType(int index)
          Returns the value of the property at the specified index in the list of properties.
 int getPropertyMode()
          Returns the mode that will be used to select results if multiple properties have been specified.
 java.lang.String getPropertyName(int index)
          Returns the name of the property at the specified index in the list of properties to be filtered on.
 java.lang.String getPropertyValue(int index)
          Returns the value of the property at the specified index in the list of properties to be filtered on.
 java.lang.String getPropertyValueString(int index)
          Returns the value of the property at the specified index in the list of properties to be filtered on.
 int getResolutionDateRangeMax()
          Returns a date that represents the upper boundry for the resolution date of questions to be selected by the result filter.
 int getResolutionDateRangeMin()
          Returns a date that represents the lower boundary for the resolution date of questions to be selected by the result filter.
 java.util.Set getResolutionStates()
          Returns the set resolution states that will be included in filtered results.
 int getSortField()
          Returns the currently selected sort field.
 int getSortOrder()
          Returns the sort order, which will be ResultFilter.ASCENDING for ascending sorting, or ResultFilter.DESCENDING for descending sorting.
 java.lang.String getSortPropertyName()
          Returns the name of the extended property that will be sorted on.
 int getStartIndex()
          Returns the index of the first result to return.
 java.util.Collection getTags()
          Returns the the ContentTags to filter on.
 long getUserID()
          Returns the userID that results will be filtered on.
 int hashCode()
           
 boolean isAllTagsRequired()
          Returns true if the content must be tagged with every tag contained in getTags().
 boolean isRecursive()
          If true, the result filter will return content from all sub-communities of specified community, including content from sub-communities of sub-communities, etc.
 void removeResolutionState(com.jivesoftware.forum.Question.State resolutionState)
          Removes a resolution state from the set of states that will be included in filtered results.
static java.util.Date roundDate(java.util.Date date, int seconds)
           
static long roundDate(long date, int seconds)
           
 void setAllTagsRequired(boolean allTagsRequired)
          Sets whether or not the content must be tagged with every tag contained in getTags().
 void setCreationDateRangeMax(java.util.Date creationDateRangeMax)
          Sets a date that represents the upper boundry for messages or threads to be selected by the result filter.
 void setCreationDateRangeMin(java.util.Date creationDateRangeMin)
          Sets the date that represents the lower boundary for messages or threads to be selected by the result filter.
 void setModerationRangeMax(int moderationRangeMax)
          Sets the upper bound for the moderation value that will pass the result filter.
 void setModerationRangeMin(int moderationRangeMin)
          Sets the moderation value that represents the lower bound for messages or threads to be selected by the result filter.
 void setModificationDateRangeMax(java.util.Date modificationDateRangeMax)
          Sets a date that represents the upper boundry for messages or threads to be selected by the result filter.
 void setModificationDateRangeMin(java.util.Date modificationDateRangeMin)
          Sets a date that represents the lower boundary for messages or threads to be selected by the result filter.
 void setNumResults(int numResults)
          Sets the limit on the number of results to be returned.
 void setPropertyMode(int propertyMode)
          Sets the mode that will be used to select results if multiple properties have been specified.
 void setRecursive(boolean recursive)
          Sets the recursive value of queries.
 void setResolutionDateRangeMax(int resolutionnDateRangeMax)
          Sets a date that represents the upper boundry for the resolution date of questions to be selected by the result filter.
 void setResolutionDateRangeMin(int resolutionDateRangeMin)
          Sets a date that represents the lower boundary for messages or threads to be selected by the result filter.
 void setSortField(int sortField)
          Sets the sort field to use.
 void setSortOrder(int sortOrder)
          Sets the sort type.
 void setSortPropertyName(java.lang.String sortPropertyName)
          Sets the property name to sort on.
 void setStartIndex(int startIndex)
          Sets the index of the first result to return.
 void setTags(java.util.Collection tags)
          Sets the ContentTags to filter on.
 void setUserID(long userID)
          Sets the userID that results will be filtered on.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DESCENDING

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

See Also:
Constant Field Values

ASCENDING

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

See Also:
Constant Field Values

EXACT_MATCH

public static final int EXACT_MATCH
Exact match.

See Also:
Constant Field Values

CONTAINS_MATCH

public static final int CONTAINS_MATCH
Contains match.

See Also:
Constant Field Values

AND_MODE

public static final int AND_MODE
'AND' mode.

See Also:
Constant Field Values

OR_MODE

public static final int OR_MODE
'OR' mode;

See Also:
Constant Field Values

NULL_INT

public static final int NULL_INT
An integer value that represents NULL. The actual value is Integer.MAX_VALUE - 123 (an arbitrary number that has a very low probability of actually being selected by a user as a valid value).

See Also:
Constant Field Values
Constructor Detail

ResultFilter

public ResultFilter()
Method Detail

createDefaultForumFilter

public static ResultFilter createDefaultForumFilter()
Creates a default forum ResultFilter: no filtering with results sorted on the category index value.


createDefaultThreadFilter

public static ResultFilter createDefaultThreadFilter()
Creates a default thread ResultFilter: no filtering with results sorted on the thread modification date.


createDefaultMessageFilter

public static ResultFilter createDefaultMessageFilter()
Creates a default message ResultFilter: no filtering with results sorted on the message creation date in ascending order.


createDefaultUserMessagesFilter

public static ResultFilter createDefaultUserMessagesFilter()
Creates a default user messages ResultFilter: no filtering with results sorted on the message creation date descending (newest messages appear first).


getUserID

public long getUserID()
Returns the userID that results will be filtered on. The method will return NULL_INT if no user to filter on has been specified. The method will return -1 if filtering is to take place on all "anonymous" users.

Returns:
the userID that results will be filtered on.

setUserID

public void setUserID(long userID)
Sets the userID that results will be filtered on. If you'd like to filter on "anonymous" users, pass in an id of -1. By default, no filtering on userID's will take place. If you'd like to change so that no filtering is performed, pass in ResultFilter.NULL_INT.

Parameters:
userID - the user ID to filter on.

addProperty

public void addProperty(java.lang.String name,
                        java.lang.String value)
Adds a property to the list of properties that will be filtered on. For a message or thread to pass the property filter: For example, say that we have a message with extended properties "color" and "size" with the values "green" and "big". If we create a result filter and specify that we should filter on "color=green" and "size=small", the hypothetical message will be filtered out since the size property values don't match.

Parameters:
name - the name of the property to filter on.
value - the value of the property that results must match.

getPropertyMode

public int getPropertyMode()
Returns the mode that will be used to select results if multiple properties have been specified. By default the mode is AND_MODE which specifies that all properties must match for the object to be selected. OR_MODE is useful if you want objects to be returned if any of the properties match.

Returns:
the mode that will be used to select results if multiple properties have been specified.

setPropertyMode

public void setPropertyMode(int propertyMode)
Sets the mode that will be used to select results if multiple properties have been specified. AND_MODE (the default) specifies that all properties must match for the object to be selected. OR_MODE is useful if you want objects to be returned if any of the properties match.

Parameters:
propertyMode - the mode that will be used to select results if multiple properties have been specified.

getPropertyCount

public int getPropertyCount()
Returns the number of properties that results will be filtered on.

Returns:
the number of properties that results will be filtered on.

getPropertyName

public java.lang.String getPropertyName(int index)
Returns the name of the property at the specified index in the list of properties to be filtered on. If the index is invalid, null will be returned.

Returns:
the name of the property at the specified index in the property filter list.

getPropertyValue

public java.lang.String getPropertyValue(int index)
Returns the value of the property at the specified index in the list of properties to be filtered on. If the index is invalid, null will be returned.

Returns:
the value of the property at the specified index in the property filter list.

getPropertyValueString

public java.lang.String getPropertyValueString(int index)
Returns the value of the property at the specified index in the list of properties to be filtered on. If the index is invalid, null will be returned.

If multiple properties are added in OR_MODE with the same name and match type, the first value in the list of values at that index will be returned.

Parameters:
index - the index of the property in the property list
Returns:
the value of the property at the specified index in the property filter list.

getPropertyMatchType

public int getPropertyMatchType(int index)
Returns the value of the property at the specified index in the list of properties. If the index is invalid, EXACT_MATCH will be returned.

Parameters:
index - the index of the property in the properties list
Returns:
the value of the property at the specified index in the property filter list.

addTag

public void addTag(ContentTag tag)
Adds a ContentTag to the list of tags to filter on. If any tags have been added to the list, only results with at least one of the tags will be returned.

Parameters:
tag - the ContentTag to filter on.

setTags

public void setTags(java.util.Collection tags)
Sets the ContentTags to filter on. Only results with at least one of the tags will be returned.

Parameters:
tags - the ContentTags to filter on.

getTags

public java.util.Collection getTags()
Returns the the ContentTags to filter on.

Returns:
the the ContentTags to filter on.

isAllTagsRequired

public boolean isAllTagsRequired()
Returns true if the content must be tagged with every tag contained in getTags().

Returns:
true if the content must be tagged with every tag contained in getTags().

setAllTagsRequired

public void setAllTagsRequired(boolean allTagsRequired)
Sets whether or not the content must be tagged with every tag contained in getTags(). Default value is false meaning content matching any one of the tags will be returned.

Parameters:
allTagsRequired - true if the content must be tagged with every tag contained in getTags().

getCreationDateRangeMin

public java.util.Date getCreationDateRangeMin()
Returns the creation date that represents the lower boundary for messages or threads to be filtered on. If this value has not been set, the method will return null.

Returns:
a Date representing the lower bound for creation dates to filter on.

setCreationDateRangeMin

public void setCreationDateRangeMin(java.util.Date creationDateRangeMin)
Sets the date that represents the lower boundary for messages or threads to be selected by the result filter. If this value is not set the results filter will be unbounded for the earliest creation date selected.

Setting a date range for a ResultFilter is a potential performance bottleneck. For example, if the argument for the date range is "new Date()" then the corresponding database query will map to an accuracy of a particular millesecond in time. This means that the results can't be cached. A better solution is to round dates to the nearest minute, hour, etc (whatever accuracy you need).

Parameters:
creationDateRangeMin - Date representing the filter lowest value of the creation date to be selected.

getCreationDateRangeMax

public java.util.Date getCreationDateRangeMax()
Returns a date that represents the upper boundry for messages or threads to be selected by the result filter. If this value is not set it will return null and the results filter will be unbounded for the latest creation date selected.

Returns:
a Date representing the filter highest value of the creation date to be selected.

setCreationDateRangeMax

public void setCreationDateRangeMax(java.util.Date creationDateRangeMax)
Sets a date that represents the upper boundry for messages or threads to be selected by the result filter. If this value is not set the results filter will be unbounded for the latest creation date selected. Setting a date range for a ResultFilter is a potential performance bottleneck. For example, if the argument for the date range is "new Date()" then the corresponding database query will map to an accuracy of a particular millesecond in time. This means that the results can't be cached. A better solution is to round dates to the nearest minute, hour, etc (whatever accuracy you need).

Parameters:
creationDateRangeMax - Date representing the filter lowest value of the creation date range.

getModificationDateRangeMin

public java.util.Date getModificationDateRangeMin()
Returns a date that represents the lower boundary for messages or threads to be selected by the result filter. If this value is not set it will return null and the results filter will be unbounded for the earliest modified date selected.

Returns:
a Date representing the filter lowest value of the modified date range.

setModificationDateRangeMin

public void setModificationDateRangeMin(java.util.Date modificationDateRangeMin)
Sets a date that represents the lower boundary for messages or threads to be selected by the result filter. If this value is not set the results filter will be unbounded for the earliest modified date selected. Setting a date range for a ResultFilter is a potential performance bottleneck. For example, if the argument for the date range is "new Date()" then the corresponding database query will map to an accuracy of a particular millesecond in time. This means that the results can't be cached. A better solution is to round dates to the nearest minute, hour, etc (whatever accuracy you need).

Parameters:
modificationDateRangeMin - Date representing the filter lowest value of the modified date to be selected.

getModificationDateRangeMax

public java.util.Date getModificationDateRangeMax()
Returns a date that represents the upper boundry for messages or threads to be selected by the result filter. If this value is not set it will return null and the results filter will be unbounded for the latest modified date selected.

Returns:
a Date representing the filter highest value of the modified date to be selected.

setModificationDateRangeMax

public void setModificationDateRangeMax(java.util.Date modificationDateRangeMax)
Sets a date that represents the upper boundry for messages or threads to be selected by the result filter. If this value is not set the results filter will be unbounded for the latest modified date selected. Setting a date range for a ResultFilter is a potential performance bottleneck. For example, if the argument for the date range is "new Date()" then the corresponding database query will map to an accuracy of a particular millesecond in time. This means that the results can't be cached. A better solution is to round dates to the nearest minute, hour, etc (whatever accuracy you need).

Parameters:
modificationDateRangeMax - Date representing the filter lowest value of the modified date range.

getSortField

public int getSortField()
Returns the currently selected sort field. The default value is JiveConstants.MODIFICATION_DATE. If the sortField is set to JiveConstants.EXTENDED_PROPERTY, the name of the property must be set by a subsequent call to setSortPropertyName(String).

Valid sort fields for object types are as follows:

Returns:
current sort field.

setSortField

public void setSortField(int sortField)
Sets the sort field to use. The default value is JiveConstants.MODIFICATION_DATE. If the sortField is set to JiveConstants.EXTENDED_PROPERTY, the name of the property must be set by a subsequent call to setSortPropertyName(String).

Valid sort fields for object types are as follows:

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

getSortPropertyName

public java.lang.String getSortPropertyName()
Returns the name of the extended property that will be sorted on. Returns null if sorting will not be done on a property.

Returns:
the extended property that will be sorted on.

setSortPropertyName

public void setSortPropertyName(java.lang.String sortPropertyName)
Sets the property name to sort on. You must also call the setSortField(int) method with JiveConstants.EXTENDED_PROPERTY as an argument.

Parameters:
sortPropertyName - the name of the extended property to sort on.

getSortOrder

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

Returns:
the sort order.

setSortOrder

public void setSortOrder(int sortOrder)
Sets the sort type. Valid arguments are ResultFilter.ASCENDING for ascending sorting or ResultFilter.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.

getNumResults

public int getNumResults()
Returns the max number of results that should be returned. The default value for is NULL_INT, which means there will be no limit on the number of results. This method can be used in combination with setStartIndex(int) to perform pagination of results.

Returns:
the max number of results to return.
See Also:
setStartIndex(int)

setNumResults

public void setNumResults(int numResults)
Sets the limit on the number of results to be returned.

Parameters:
numResults - the number of results to return.

getStartIndex

public int getStartIndex()
Returns the index of the first result to return.

Returns:
the index of the first result which should be returned.

setStartIndex

public void setStartIndex(int startIndex)
Sets the index of the first result to return. For example, if the start index is set to 20, the Iterator returned will start at the 20th result in the query. This method can be used in combination with setNumResults(int) to perform pagination of results.

Parameters:
startIndex - the index of the first result to return.

getModerationRangeMin

public int getModerationRangeMin()
Returns the moderation value that represents the lower boundry for messages or threads to be selected by the result filter. If this value is not set it will return the lowest moderation value allowed and the results filter will be unbounded for the lowest moderation value selected. For example -- if boolean moderation is being used, the possible values that can be expected of a message are -1 for rejected messages, 0 unapproved messages, and 1 for approved messages. To show messages available for the general public, you would pass this accessor a minimum value of 1 and a maximum value of 1 or higher. To show messages in need of moderation you would pass this accessor a minimum value of 0 and a maximum value of 0. To show messages in need of moderation in the context of threads that are already approved, you would pass this accessor a minumum value of 0 and a maximum value of 1.

Returns:
an int representing the lowest value of the moderation value to be selected by the filter.

setModerationRangeMin

public void setModerationRangeMin(int moderationRangeMin)
Sets the moderation value that represents the lower bound for messages or threads to be selected by the result filter. If this value is not set, the lower bound will default to JiveConstants.FORUM_MODERATION_VISIBLE.

Parameters:
moderationRangeMin - int representing the lowest value of the moderation value range to be selected by the result filter.

getModerationRangeMax

public int getModerationRangeMax()
Returns the moderation value that represents the upper bound for messages or threads to be selected by the result filter. If an upper bound has not been set, this method will return ResultFilter.NULL_INT.

Returns:
the upper bound for moderation values to filter on.

setModerationRangeMax

public void setModerationRangeMax(int moderationRangeMax)
Sets the upper bound for the moderation value that will pass the result filter. If this value is not set, or is set to ResultFilter.NULL_INT there will be no upper bound on moderation values.

Parameters:
moderationRangeMax - the max value of the moderation value range.

getResolutionStates

public java.util.Set getResolutionStates()
Returns the set resolution states that will be included in filtered results. By default, all resolution states are included.

Returns:
the set of resolution states that will be included in filtered results.

addResolutionState

public void addResolutionState(com.jivesoftware.forum.Question.State resolutionState)
Adds a resolution state to the set of states that will be included in filtered results.

Parameters:
resolutionState - resolution state.

removeResolutionState

public void removeResolutionState(com.jivesoftware.forum.Question.State resolutionState)
Removes a resolution state from the set of states that will be included in filtered results.

Parameters:
resolutionState - resolution state.

clearResolutionStates

public void clearResolutionStates()
Removes all resolution states from the set of states that will be included in filtered results.


getResolutionDateRangeMin

public int getResolutionDateRangeMin()
Returns a date that represents the lower boundary for the resolution date of questions to be selected by the result filter. If this value is not set it will return null and the results filter will be unbounded for the earliest modified date selected.

Returns:
the lowest value of the resolution date to be selected by the filter.

setResolutionDateRangeMin

public void setResolutionDateRangeMin(int resolutionDateRangeMin)
Sets a date that represents the lower boundary for messages or threads to be selected by the result filter. If this value is not set the results filter will be unbounded for the earliest modified date selected. Setting a date range for a QuestionFilter is a potential performance bottleneck. For example, if the argument for the date range is "new Date()" then the corresponding database query will map to an accuracy of a particular millesecond in time. This means that the results can't be cached. A better solution is to round dates to the nearest minute, hour, etc (whatever accuracy you need).

Parameters:
resolutionDateRangeMin - the lowest value of the resolution date to be selected by the filter.

getResolutionDateRangeMax

public int getResolutionDateRangeMax()
Returns a date that represents the upper boundry for the resolution date of questions to be selected by the result filter. If this value is not set it will return null and the filter will be unbounded for the resolution date.

Returns:
the highest value of the resolution date to be selected by the filter.

setResolutionDateRangeMax

public void setResolutionDateRangeMax(int resolutionnDateRangeMax)
Sets a date that represents the upper boundry for the resolution date of questions to be selected by the result filter. If this value is not set the filter will be unbounded for the resolution date. Setting a date range for a QuestionFilter is a potential performance bottleneck. For example, if the argument for the date range is "new Date()" then the corresponding database query will map to an accuracy of a particular millesecond in time. This means that the results can't be cached. A better solution is to round dates to the nearest minute, hour, etc (whatever accuracy you need).

Parameters:
resolutionnDateRangeMax - the highest value of the resolution date to be selected by the filter.

roundDate

public static java.util.Date roundDate(java.util.Date date,
                                       int seconds)
See Also:
DateUtils.roundDate(Date, int)

roundDate

public static long roundDate(long date,
                             int seconds)
See Also:
DateUtils.roundDate(long, int)

clone

public java.lang.Object clone()
Clones a ResultFilter

Overrides:
clone in class java.lang.Object

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

isRecursive

public boolean isRecursive()
If true, the result filter will return content from all sub-communities of specified community, including content from sub-communities of sub-communities, etc. If false, only content from the specified community will be returned.

The default value of this is false which means that queries will be done in a non-recursive manner.

Returns:
true if this result filter should return recursive content, false otherwise.

setRecursive

public void setRecursive(boolean recursive)
Sets the recursive value of queries. If set to true then database results will be done over an entire tree of communities, rather than in a specific community.

The default value of this is false which means only one community (and not its children) will be considered in results.

Parameters:
recursive - true if this result filter should return recursive content, false otherwise.

createDefaultContentFilter

public static ResultFilter createDefaultContentFilter()
Creates a default ResultFilter: no filtering with results sorted on the modification date.

Returns:
a default ResultFilter: no filtering with results sorted on the modification date.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.