Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum.webservices
Class ResultFilter

java.lang.Object
  extended by com.jivesoftware.forum.webservices.ResultFilter

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.


Field Summary
static int ASCENDING
          Ascending sort (ie 3, 4, 5...).
static int DESCENDING
          Descending sort (ie 3, 2, 1...).
static int NULL_INT
          An integer value that represents NULL.
 
Constructor Summary
ResultFilter()
           
 
Method Summary
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 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.
 int getStartIndex()
          Returns the index of the first result to return.
 long getUserID()
          Returns the userID that results will be filtered on.
 int hashCode()
           
 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 setSortField(int sortField)
          Sets the sort field to use.
 void setSortOrder(int sortOrder)
          Sets the sort type.
 void setStartIndex(int startIndex)
          Sets the index of the first result to return.
 void setUserID(long userID)
          Sets the userID that results will be filtered on.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, 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

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.

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.

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.

Valid sort fields for object types are as follows:

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

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 1 (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.

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

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.