com.jivesoftware.community
Interface StatusLevelManager

public interface StatusLevelManager

Manages status level feature. StatusLevel levels allow the system to rank users by points or associate users with a specific group.

See Also:

StatusLevel

Method Summary

void	addPoints(User user, JiveContainer container, JiveObject object, long points, String code) Rewards points to a user.
void	addPoints(User user, JiveContainer container, JiveObject jiveObject, String scenarioCode) Give points to a user using the specified scenerio code.
int	countTimesAwarded(User user, JiveObject target) Counts the number of times a user has been awarded against a particular object.
StatusLevel	createStatusLevel(String name, String imagePath, Group group) Creates a new group based StatusLevel Level
StatusLevel	createStatusLevel(String name, String imagePath, int minPoints, int maxPoints) Creates a new points based StatusLevel.
void	deleteStatusLevel(StatusLevel statusLevel) Deletes a statusLevel level from the system
void	deleteUserStatusLevels(User user) Deletes all statusLevel levels for a given user from the system.
Map<JiveContainer,Long>	getAllPointLevels(User user) Returns a map of community -> status level points for all the communities the user has points in.
List<StatusLevelScenario>	getAllStatusLevelScenarios() Returns all of the com.jivesoftware.community.StatusLevelScenario objects.
Iterable<StatusLevel>	getGroupStatusLevels() Returns an iterable of all group based status levels in the system.
Iterable<User>	getLeaders() Returns an Iterable of system wide leaders.
Iterable<User>	getLeaders(int startIndex, int numResults) Returns an Iterable of system wide leaders.
Iterable<User>	getLeaders(JiveContainer container) Returns an Iterable of leaders for a specific container
Iterable<User>	getLeaders(JiveContainer container, int startIndex, int numResults) Returns an Iterable of leaders for a specific container
long	getPointLevel(User user) Returns the point level for a user system wide.
long	getPointLevel(User user, JiveContainer container) Returns the status level points for a user in regards to a specific container
Iterable<StatusLevel>	getPointStatusLevels() Returns an iterable of point based status levels in the system sorted by point range.
StatusLevel	getStatusLevel(Group group) If there is a status level associated with the group passed in then the status level will be returned, Otherwise null will be returned.
StatusLevel	getStatusLevel(long statusLevelID) Used to acquire a specific status level object from the system
StatusLevel	getStatusLevel(String name) Used to acquire a specific status level by its name
StatusLevel	getStatusLevel(User user) Returns the system wide status level for specific user, will return null if there is no status level for this user.
StatusLevel	getStatusLevel(User user, JiveContainer container) Returns the status level for a user in a specific container. if a status level cannot be determined for this user in this container null will be returned.
StatusLevel	getStatusLevelByPoints(long points) Used to get a status level by a point value.
StatusLevelScenario	getStatusLevelScenarioByCode(String code) Returns a com.jivesoftware.community.StatusLevelScenario by its code.
boolean	isStatusLevelsEnabled() Returns true if status levels are enabled in the system
void	setStatusLevelsEnabled(boolean statusLevelEnabled) Sets whether status levels should be enabled in the system.
void	updateStatusLevelScenario(StatusLevelScenario scenario) Update the points and whether or not this scenario is included in status level results.

Method Detail

createStatusLevel

StatusLevel createStatusLevel(String name,
                              String imagePath,
                              int minPoints,
                              int maxPoints)
                              throws UnauthorizedException,
                                     StatusLevelException,
                                     StatusLevelAlreadyExistsException

Creates a new points based StatusLevel. The minPoints and maxPoints range must not intersect, and maxPoints cannot be zero. Specify -1 in either to denote a boundless range (ie minPoints=50, maxPoints=-1 would mean everything over 50 has this status level)

The minPoints and maxPoints values must not go into the range over another StatusLevel levels point range.

Parameters:

name - name of the status level

imagePath - The path the image used when displaying this status level.

minPoints - minimum amount in the point range

maxPoints - maximum amount in the point range

Returns:

The newly created status level object

Throws:

UnauthorizedException - if not system admin

StatusLevelException - if an illegal range is specified.

StatusLevelAlreadyExistsException - Thrown if there is a status level already matching these criteria.

createStatusLevel

StatusLevel createStatusLevel(String name,
                              String imagePath,
                              Group group)
                              throws UnauthorizedException,
                                     StatusLevelException,
                                     StatusLevelAlreadyExistsException

Creates a new group based StatusLevel Level

Parameters:

name - name of the status level

imagePath - The path the image used when displaying this status level.

group - group to associate this status level with

Returns:

newly created status level object

Throws:

UnauthorizedException - if not system admin

StatusLevelException - If this status level cannot be created.

StatusLevelAlreadyExistsException - Thrown if there is a status level already matching these criteria.

deleteStatusLevel

void deleteStatusLevel(StatusLevel statusLevel)
                       throws UnauthorizedException

Deletes a statusLevel level from the system

Parameters:

statusLevel - statusLevel level to delete

Throws:

UnauthorizedException - if not system admin

deleteUserStatusLevels

void deleteUserStatusLevels(User user)
                            throws UnauthorizedException

Deletes all statusLevel levels for a given user from the system.

Parameters:

user - the owner of the statusLevels being deleted.

Throws:

UnauthorizedException - if not system-admin or user-admin

getGroupStatusLevels

Iterable<StatusLevel> getGroupStatusLevels()

Returns an iterable of all group based status levels in the system.

Returns:

an iterable of all group based status levels in the system.

getPointStatusLevels

Iterable<StatusLevel> getPointStatusLevels()

Returns an iterable of point based status levels in the system sorted by point range.

Returns:

point range sorted iterable of StatusLevel objects

getLeaders

Iterable<User> getLeaders()

Returns an Iterable of system wide leaders.

Returns:

Iterable of User objects for system wide leaders

getLeaders

Iterable<User> getLeaders(int startIndex,
                          int numResults)

Returns an Iterable of system wide leaders.

Parameters:

startIndex - The starting point of the results.

numResults - The number of results to return in the iterable.

Returns:

Iterable of User objects for system wide leaders

getLeaders

Iterable<User> getLeaders(JiveContainer container)

Returns an Iterable of leaders for a specific container

Parameters:

container -

Returns:

Iterable of User objects for a specific forum

getLeaders

Iterable<User> getLeaders(JiveContainer container,
                          int startIndex,
                          int numResults)

Returns an Iterable of leaders for a specific container

Parameters:

startIndex - The starting point of the leader results.

numResults - The number of results in the iterable.

Returns:

Iterable of User objects for a specific forum @param container

getStatusLevel

StatusLevel getStatusLevel(long statusLevelID)
                           throws StatusLevelNotFoundException

Used to acquire a specific status level object from the system

Parameters:

statusLevelID - the id of the object to acquire

Returns:

the object found in the system

Throws:

StatusLevelNotFoundException - thrown if the object does not exist in the system

getStatusLevel

StatusLevel getStatusLevel(String name)
                           throws StatusLevelNotFoundException

Used to acquire a specific status level by its name

Parameters:

name - name of the status level

Returns:

the object found in the system

Throws:

StatusLevelNotFoundException - thrown if the object does not exist in the system

getStatusLevel

StatusLevel getStatusLevel(User user)

Returns the system wide status level for specific user, will return null if there is no status level for this user.

If the user belongs to a group status level the group status level will always be returned.

Parameters:

user - user to find the status level for

Returns:

system wide status level for the user or null if no status level

getStatusLevel

StatusLevel getStatusLevel(User user,
                           JiveContainer container)

Returns the status level for a user in a specific container. if a status level cannot be determined for this user in this container null will be returned.

If the user belongs to a group status level the group status level will always be returned.

Parameters:

user - user to find the status level for

container - container to check the status level for

Returns:

container specific status level or null if no status level can be determined

setStatusLevelsEnabled

void setStatusLevelsEnabled(boolean statusLevelEnabled)
                            throws UnauthorizedException

Sets whether status levels should be enabled in the system.

Parameters:

statusLevelEnabled - true if status levels are enabled, else false

Throws:

UnauthorizedException - if not system admin

isStatusLevelsEnabled

boolean isStatusLevelsEnabled()

Returns true if status levels are enabled in the system

Returns:

true if status levels are enabled

getStatusLevelByPoints

StatusLevel getStatusLevelByPoints(long points)

Used to get a status level by a point value. If the points exceeds that of the maximum status level, the maximum status level will be returned.

Parameters:

points - point value find a status level for

Returns:

the StatusLevel matching a point level, or null if non is found

getPointLevel

long getPointLevel(User user)

Returns the point level for a user system wide.

Parameters:

user - user to get status level points for

Returns:

how many status points the user has

getPointLevel

long getPointLevel(User user,
                   JiveContainer container)

Returns the status level points for a user in regards to a specific container

Parameters:

user - user user to get status level points for

container - container to filter by

Returns:

how many status level points a user has for the particular container

getAllPointLevels

Map<JiveContainer,Long> getAllPointLevels(User user)

Returns a map of community -> status level points for all the communities the user has points in.

Parameters:

user - user user to get status level points for

Returns:

how many status level points a user has for the particular container

getStatusLevel

StatusLevel getStatusLevel(Group group)

If there is a status level associated with the group passed in then the status level will be returned, Otherwise null will be returned.

Parameters:

group - group to find a status level for

Returns:

status level that is associated with group, else null

addPoints

void addPoints(User user,
               JiveContainer container,
               JiveObject object,
               long points,
               String code)

Rewards points to a user. By providing the object and a reason we can tell which object the user is be rewarded on and a code explaining why.

Note that it is valid to submit negative point values to remove points from a user.

Parameters:

user - The user who is receiving points.

container - The container the points are added to.

object - The object the user should receive points on.

points - Amount of points to award the user.

code - A code explaining why the user is receiving points.

getAllStatusLevelScenarios

List<StatusLevelScenario> getAllStatusLevelScenarios()

Returns all of the com.jivesoftware.community.StatusLevelScenario objects.

Returns:

all of the com.jivesoftware.community.StatusLevelScenario objects.

updateStatusLevelScenario

void updateStatusLevelScenario(StatusLevelScenario scenario)

Update the points and whether or not this scenario is included in status level results.

Parameters:

scenario - the points and whether or not this scenario is included in status level results.

getStatusLevelScenarioByCode

StatusLevelScenario getStatusLevelScenarioByCode(String code)

Returns a com.jivesoftware.community.StatusLevelScenario by its code.

Parameters:

code - The code of the StatusLevelScenario.

Returns:

The matching StatusLevelScenario.

addPoints

void addPoints(User user,
               JiveContainer container,
               JiveObject jiveObject,
               String scenarioCode)

Give points to a user using the specified scenerio code.

Parameters:

user - The user to award points too.

container - The container that the points were awarded in.

jiveObject - object points were awarded on.

scenarioCode - The scenario code.

countTimesAwarded

int countTimesAwarded(User user,
                      JiveObject target)

Counts the number of times a user has been awarded against a particular object.

Parameters:

user -

target - The object awarded against.

Returns:

The number of times awarded.

Since:

2.0