com.jivesoftware.community
Interface PresenceManager

All Superinterfaces:

JiveManager

public interface PresenceManager
extends JiveManager

The presence manager creates presences and keeps track on a global basis who's online. Also included is the ability to enable or disable global presence support.

Field Summary

static int	SORT_ONLINE_TIME Sort by online time.
static int	SORT_USERNAME Sort by username.

Method Summary

Presence	createPresence(User user, String uid, String IPAddress) Create a presence for a user.
void	deletePresence(User user) Remove the given user's presence and roster entry.
int	getOnlineUserCount() Returns the number of users who are currently online.
int	getOnlineUserCount(Group group) Returns the number of users in the group who are currently online.
Iterator<User>	getOnlineUsers() Returns an iterator of users who are currently online.
Iterator<User>	getOnlineUsers(boolean ascending, int sortField) Returns an iterator of users sorted in the manner requested who are currently online.
Iterator<User>	getOnlineUsers(boolean ascending, int sortField, int numResults) Returns an iterator of users who are currently online matching the criteria given.
Iterator<User>	getOnlineUsers(boolean ascending, int sortField, int start, int numResults) Returns an iterator of users who are currently online matching the criteria given.
Iterator<User>	getOnlineUsers(Group group) Returns an iterator of users in the group who are currently online.
Iterator<User>	getOnlineUsers(Group group, boolean ascending, int sortField) Returns an iterator of users sorted in the manner requested who are currently online.
Iterator<User>	getOnlineUsers(Group group, boolean ascending, int sortField, int numResults) Returns an iterator of users who are currently online matching the criteria given.
Presence	getPresence(User user) Returns the presence for the user, or null if the user isn't online.
Roster	getRoster(User user) Returns the user's roster.
boolean	isOnline(User user) Returns whether the user is currently online or not.
boolean	isPresencesEnabled() Returns whether presences are enabled on a global basis or not.
void	setOffline(Presence presence) Sets a presence to be offline which causes the presence to be removed from the system.
void	setPresencesEnabled(boolean enabled) Sets whether presences are enabled on a global basis or not.

Methods inherited from interface com.jivesoftware.community.JiveManager

destroy

Field Detail

SORT_USERNAME

static final int SORT_USERNAME

Sort by username.

See Also:

Constant Field Values

SORT_ONLINE_TIME

static final int SORT_ONLINE_TIME

Sort by online time.

See Also:

Constant Field Values

Method Detail

isPresencesEnabled

boolean isPresencesEnabled()

Returns whether presences are enabled on a global basis or not.

Returns:

whether presences are enabled on a global basis or not.

setPresencesEnabled

void setPresencesEnabled(boolean enabled)
                         throws UnauthorizedException

Sets whether presences are enabled on a global basis or not.

Parameters:

enabled - true if presences should be enabled, false otherwise.

Throws:

UnauthorizedException - if not a system administrator.

getOnlineUserCount

int getOnlineUserCount()

Returns the number of users who are currently online. Online users with a presence status set to invisible will not be included.

Returns:

the number of online users.

getOnlineUserCount

int getOnlineUserCount(Group group)

Returns the number of users in the group who are currently online. Online users with a presence status set to invisible will not be included.

Parameters:

group - the group to return the online user count.

Returns:

the number of online users in the group.

isOnline

boolean isOnline(User user)

Returns whether the user is currently online or not. If the user's status is set to Presence.STATUS_INVISIBLE, the user will never show up as online.

Parameters:

user - the user to check to see if they're online.

Returns:

whether the user is currently online or not.

getOnlineUsers

Iterator<User> getOnlineUsers()

Returns an iterator of users who are currently online. Online users with a presence status other that online or idle will not be included.

Returns:

an iterator of online users.

getOnlineUsers

Iterator<User> getOnlineUsers(Group group)

Returns an iterator of users in the group who are currently online. Online users with a presence statas set to invisible will not be included.

Parameters:

group - the group to return the online users.

Returns:

an iterator of online users in the group.

getOnlineUsers

Iterator<User> getOnlineUsers(boolean ascending,
                              int sortField)

Returns an iterator of users sorted in the manner requested who are currently online. Online users with a presence status other that online or idle will not be included.

Parameters:

ascending - sort ascending if true, descending if false.

sortField - a valid sort field from the PresenceManager interface.

Returns:

an iterator of online users.

getOnlineUsers

Iterator<User> getOnlineUsers(Group group,
                              boolean ascending,
                              int sortField)

Returns an iterator of users sorted in the manner requested who are currently online. Online users with a presence status other that online or idle will not be included.

Parameters:

group - the group to return the online users.

ascending - sort ascending if true, descending if false.

sortField - a valid sort field from the PresenceManager interface.

Returns:

an iterator of online users in the group.

getOnlineUsers

Iterator<User> getOnlineUsers(boolean ascending,
                              int sortField,
                              int numResults)

Returns an iterator of users who are currently online matching the criteria given. Online users with a presence status other than online or idle will not be included.

Parameters:

ascending - sort ascending if true, descending if false.

sortField - a valid sort field from the PresenceManager interface.

numResults - - the number of results to return.

Returns:

an iterator of online users matching the given criteria.

getOnlineUsers

Iterator<User> getOnlineUsers(boolean ascending,
                              int sortField,
                              int start,
                              int numResults)

Returns an iterator of users who are currently online matching the criteria given. Online users with a presence status other than online or idle will not be included.

Parameters:

ascending - sort ascending if true, descending if false.

sortField - a valid sort field from the PresenceManager interface.

start - the index into the sorted set of users to start iterating from.

numResults - - the number of results to return.

Returns:

an iterator of online users matching the given criteria.

getOnlineUsers

Iterator<User> getOnlineUsers(Group group,
                              boolean ascending,
                              int sortField,
                              int numResults)

Returns an iterator of users who are currently online matching the criteria given. Online users with a presence status other than online or idle will not be included.

Parameters:

group - the group to narrow users down to

ascending - sort ascending if true, descending if false.

sortField - a valid sort field from the PresenceManager interface.

numResults - - the number of results to return.

Returns:

an iterator of online users matching the given criteria.

getPresence

Presence getPresence(User user)

Returns the presence for the user, or null if the user isn't online.

Parameters:

user - the user to return the presence for.

Returns:

the presence for the user, or null if the user isn't online.

getRoster

Roster getRoster(User user)
                 throws UnauthorizedException

Returns the user's roster. A roster is a list of users that the user wishes to know if they are online. Rosters are similar to buddy groups in popular IM clients.

Parameters:

user - the user to return the roster for.

Returns:

the user's roster.

Throws:

UnauthorizedException - if not the user or an administrator.

createPresence

Presence createPresence(User user,
                        String uid,
                        String IPAddress)
                        throws UnauthorizedException

Create a presence for a user. Creating a presence will automatically set the user to be online.

The uid should be unique within the application instance. A good source of a uid is the servlet session id.

Parameters:

user - the user to create a presence for.

uid - a unique string.

IPAddress - the IP address of the user.

Returns:

the presence for the user.

Throws:

UnauthorizedException - if not the user.

deletePresence

void deletePresence(User user)
                    throws UnauthorizedException

Remove the given user's presence and roster entry.

Parameters:

user - having their presence removed

Throws:

UnauthorizedException - If currently authenticated user is not a sys-admin.

setOffline

void setOffline(Presence presence)
                throws UnauthorizedException

Sets a presence to be offline which causes the presence to be removed from the system.

Parameters:

presence - to presence to set to be offline.

Throws:

UnauthorizedException - if not the user.