org.jivesoftware.wildfire
Class SessionResultFilter

java.lang.Object
  org.jivesoftware.wildfire.SessionResultFilter

public class SessionResultFilter
extends Object

Filters and sorts lists of sessions. This allows for a very rich set of possible queries that can be run on session data. Some examples are: "Show all sessions started during the last hour by a certain user".

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.

Factory methods to create common queries are provided for convenience.

Author:

Matt Tucker

Field Summary

static int	ASCENDING Ascending sort (ie 3, 4, 5...).
static int	DESCENDING Descending sort (ie 3, 2, 1...).
static long	NO_PACKET_LIMIT Represents no result limit (infinite results).
static int	NO_RESULT_LIMIT Represents no result limit (infinite results).
static int	SORT_CREATION_DATE
static int	SORT_LAST_ACTIVITY_DATE
static int	SORT_NUM_CLIENT_PACKETS
static int	SORT_NUM_SERVER_PACKETS
static int	SORT_USER

Constructor Summary

SessionResultFilter()

Method Summary

static SessionResultFilter	createDefaultSessionFilter() Creates a default SessionResultFilter: no filtering with results sorted by user (ascending).
boolean	equals(Object object)
long	getClientPacketRangeMax() Returns the upper boundary on client packets for sessions to be selected by the result filter.
long	getClientPacketRangeMin() Returns the lower boundary on client packets for sessions to be selected by the result filter.
Date	getCreationDateRangeMax() Returns a date that represents the upper boundry for sessions to be selected by the result filter.
Date	getCreationDateRangeMin() Returns the creation date that represents the lower boundary for sessions to be filtered on.
Date	getLastActivityDateRangeMax() Returns a date that represents the upper boundry for sessions to be selected by the result filter.
Date	getLastActivityDateRangeMin() Returns a date that represents the lower boundary for session to be selected by the result filter.
int	getNumResults() Returns the max number of results that should be returned.
long	getServerPacketRangeMax() Returns the upper boundary on server packets for sessions to be selected by the result filter.
long	getServerPacketRangeMin() Returns the lower boundary on server packets for sessions to be selected by the result filter.
Comparator<Session>	getSortComparator() Returns a comparator that will sort a standard sorted set according to this filter's sort order.
int	getSortField() Returns the currently selected sort field.
int	getSortOrder() Returns the sort order, which will be SessionResultFilter.ASCENDING for ascending sorting, or SessionResultFilter.DESCENDING for descending sorting.
int	getStartIndex() Returns the index of the first result to return.
String	getUsername() Returns the username that results will be filtered on.
static Date	roundDate(Date date, int seconds) Rounds the given date down to the nearest specified second.
static long	roundDate(long date, int seconds) Rounds the given date down to the nearest specfied second.
void	setClientPacketRangeMax(long max) Sets the upper boundary on client packets for sessions to be selected by the result filter.
void	setClientPacketRangeMin(long min) Sets the lower boundary on client packets for sessions to be selected by the result filter.
void	setCreationDateRangeMax(Date creationDateRangeMax) Sets a date that represents the upper boundry for sessions to be selected by the result filter.
void	setCreationDateRangeMin(Date creationDateRangeMin) Sets the date that represents the lower boundary for sessions to be selected by the result filter.
void	setLastActivityDateRangeMax(Date lastActivityDateRangeMax) Sets a date that represents the upper boundry for sessions to be selected by the result filter.
void	setLastActivityDateRangeMin(Date lastActivityDateRangeMin) Sets a date that represents the lower boundary for sessions to be selected by the result filter.
void	setNumResults(int numResults) Sets the limit on the number of results to be returned.
void	setServerPacketRangeMax(long max) Sets the upper boundary on server packets for sessions to be selected by the result filter.
void	setServerPacketRangeMin(long min) Sets the lower boundary on server packets for sessions 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	setStartIndex(int startIndex) Sets the index of the first result to return.
void	setUsername(String username) Sets the username that results will be filtered on.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, 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

NO_RESULT_LIMIT

public static final int NO_RESULT_LIMIT

Represents no result limit (infinite results).

See Also:

Constant Field Values

NO_PACKET_LIMIT

public static final long NO_PACKET_LIMIT

Represents no result limit (infinite results).

See Also:

Constant Field Values

SORT_USER

public static final int SORT_USER

See Also:

Constant Field Values

SORT_CREATION_DATE

public static final int SORT_CREATION_DATE

See Also:

Constant Field Values

SORT_LAST_ACTIVITY_DATE

public static final int SORT_LAST_ACTIVITY_DATE

See Also:

Constant Field Values

SORT_NUM_CLIENT_PACKETS

public static final int SORT_NUM_CLIENT_PACKETS

See Also:

Constant Field Values

SORT_NUM_SERVER_PACKETS

public static final int SORT_NUM_SERVER_PACKETS

See Also:

Constant Field Values

Constructor Detail

SessionResultFilter

public SessionResultFilter()

Method Detail

createDefaultSessionFilter

public static SessionResultFilter createDefaultSessionFilter()

Creates a default SessionResultFilter: no filtering with results sorted by user (ascending).

getUsername

public String getUsername()

Returns the username that results will be filtered on. The method will return null if no user to filter on has been specified.

Returns:

the username that results will be filtered on.

setUsername

public void setUsername(String username)

Sets the username that results will be filtered on. By default, no filtering on username will take place. To avoid filtering on username pass in null.

Parameters:

username - the user ID to filter on.

getCreationDateRangeMin

public Date getCreationDateRangeMin()

Returns the creation date that represents the lower boundary for sessions 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(Date creationDateRangeMin)

Sets the date that represents the lower boundary for sessions 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.

Parameters:

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

getCreationDateRangeMax

public Date getCreationDateRangeMax()

Returns a date that represents the upper boundry for sessions 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(Date creationDateRangeMax)

Sets a date that represents the upper boundry for sessions 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.

Parameters:

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

getLastActivityDateRangeMin

public Date getLastActivityDateRangeMin()

Returns a date that represents the lower boundary for session 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 last activity date selected.

Returns:

a Date representing the filter lowest value of the last activity date range.

setLastActivityDateRangeMin

public void setLastActivityDateRangeMin(Date lastActivityDateRangeMin)

Sets a date that represents the lower boundary for sessions to be selected by the result filter. If this value is not set the results filter will be unbounded for the earliest last activity date selected.

Parameters:

lastActivityDateRangeMin - Date representing the filter lowest value of the last activity date to be selected.

getLastActivityDateRangeMax

public Date getLastActivityDateRangeMax()

Returns a date that represents the upper boundry for sessions 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 activity date selected.

Returns:

a Date representing the filter highest value of the last activity date to be selected.

setLastActivityDateRangeMax

public void setLastActivityDateRangeMax(Date lastActivityDateRangeMax)

Sets a date that represents the upper boundry for sessions to be selected by the result filter. If this value is not set the results filter will be unbounded for the latest activity date selected.

Parameters:

lastActivityDateRangeMax - Date representing the filter lowest value of the last activity date range.

getClientPacketRangeMin

public long getClientPacketRangeMin()

Returns the lower boundary on client packets for sessions to be selected by the result filter. A value of NO_PACKET_LIMIT will be returned if there is no lower packet limit.

Returns:

the lower limit of client packets allowed for sessions to meet this filter requirement.

setClientPacketRangeMin

public void setClientPacketRangeMin(long min)

Sets the lower boundary on client packets for sessions to be selected by the result filter. If this value is not set (using the value NO_PACKET_LIMIT), the results filter will have no lower bounds for client packets selected.

Parameters:

min - the lower limit of client packets allowed for sessions to meet this filter requirement.

getClientPacketRangeMax

public long getClientPacketRangeMax()

Returns the upper boundary on client packets for sessions to be selected by the result filter. A value of NO_PACKET_LIMIT will be returned if there is no upper packet limit.

Returns:

the upper limit of client packets allowed for sessions to meet this filter requirement.

setClientPacketRangeMax

public void setClientPacketRangeMax(long max)

Sets the upper boundary on client packets for sessions to be selected by the result filter. If this value is not set (using the value NO_PACKET_LIMIT), the results filter will have no upper bounds for client packets selected.

Parameters:

max - the upper limit of client packets allowed for sessions to meet this filter requirement.

getServerPacketRangeMin

public long getServerPacketRangeMin()

Returns the lower boundary on server packets for sessions to be selected by the result filter. A value of NO_PACKET_LIMIT will be returned if there is no lower packet limit.

Returns:

the lower limit of server packets allowed for sessions to meet this filter requirement.

setServerPacketRangeMin

public void setServerPacketRangeMin(long min)

Sets the lower boundary on server packets for sessions to be selected by the result filter. If this value is not set (using the value NO_PACKET_LIMIT), the results filter will have no lower bounds for server packets selected.

Parameters:

min - the lower limit of server packets allowed for sessions to meet this filter requirement.

getServerPacketRangeMax

public long getServerPacketRangeMax()

Returns the upper boundary on server packets for sessions to be selected by the result filter. A value of NO_PACKET_LIMIT will be returned if there is no upper packet limit.

Returns:

the upper limit of server packets allowed for sessions to meet this filter requirement.

setServerPacketRangeMax

public void setServerPacketRangeMax(long max)

Sets the upper boundary on server packets for sessions to be selected by the result filter. If this value is not set (using the value NO_PACKET_LIMIT), the results filter will have no upper bounds for server packets selected.

Parameters:

max - the upper limit of server packets allowed for sessions to meet this filter requirement.

getSortField

public int getSortField()

Returns the currently selected sort field. The default value is SessionResultFilter.SORT_LAST_ACTIVITY_DATE.

Returns:

current sort field.

setSortField

public void setSortField(int sortField)

Sets the sort field to use. The default value is SessionResultFilter.SORT_LAST_ACTIVITY_DATE.

Parameters:

sortField - the field that will be used for sorting.

getSortOrder

public int getSortOrder()

Returns the sort order, which will be SessionResultFilter.ASCENDING for ascending sorting, or SessionResultFilter.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 SessionResultFilter.ASCENDING for ascending sorting or SessionResultFilter.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 NO_RESULT_LIMIT, 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 or NO_RESULT_LIMIT for no limit

See Also:

setStartIndex(int)

setNumResults

public void setNumResults(int numResults)

Sets the limit on the number of results to be returned.

User NO_RESULT_LIMIT if you don't want to limit the results returned.

Parameters:

numResults - the number of results to return or NO_RESULT_LIMIT for no limit

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.

getSortComparator

public Comparator<Session> getSortComparator()

Returns a comparator that will sort a standard sorted set according to this filter's sort order.

Returns:

a comparator that sorts Sessions matching the sort order for this filter.

roundDate

public static Date roundDate(Date date,
                             int seconds)

Rounds the given date down to the nearest specified second. The following table shows sample input and expected output values: (Note, only the time portion of the date is shown for brevity)

Date	Seconds	Result
1:37.48	5	1:37.45
1:37.48	10	1:37.40
1:37.48	30	1:37.30
1:37.48	60	1:37.00
1:37.48	120	1:36.00

This method is useful when calculating the last post in a forum or the number of new messages from a given date. Using a rounded date allows Jive to internally cache the results of the date query. Here's an example that shows the last posted message in a forum accurate to the last 60 seconds:

 SessionResultFilter filter = new SessionResultFilter();
 filter.setSortOrder(SessionResultFilter.DESCENDING);
 filter.setSortField(JiveGlobals.SORT_CREATION_DATE);
 filter.setCreationDateRangeMin(SessionResultFilter.roundDate(forum.getModificationDate(), 60));
 filter.setNumResults(1);
 Iterator messages = forum.messages(filter);
 ForumMessage lastPost = (ForumMessage)messages.next();
 

Parameters:

date - the Date we want to round.

seconds - the number of seconds we want to round the date to.

Returns:

the given date, rounded down to the nearest specified number of seconds.

roundDate

public static long roundDate(long date,
                             int seconds)

Rounds the given date down to the nearest specfied second.

Parameters:

date - the date (as a long) that we want to round.

seconds - the number of seconds we want to round the date to.

Returns:

the given date (as a long), rounded down to the nearest specified number of seconds.

equals

public boolean equals(Object object)

Overrides:

equals in class Object