com.jivesoftware.community.webservices
Interface StatusLevelService

public interface StatusLevelService

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

Method Summary

void	addPoints(long userID, long communityID, long objectID, int objectType, long points, java.lang.String code) Rewards points to a user.
StatusLevel	createStatusLevel(java.lang.String name, java.lang.String imagePath, int minPoints, int maxPoints) Creates a new points based StatusLevel.
StatusLevel	createStatusLevel(java.lang.String name, java.lang.String imagePath, long groupID) Creates a new group based StatusLevel Level
void	deleteStatusLevel(long statusLevelID) Deletes a statusLevel level from the system
StatusLevelScenario[]	getAllStatusLevelScenarios() Returns all of the StatusLevelScenario objects.
StatusLevel	getGroupStatusLevel(long groupID) 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[]	getGroupStatusLevels() Returns an array of all group based status levels in the system.
User[]	getLeaders() Returns an array of system wide leaders.
User[]	getLeaders(int startIndex, int numResults) Returns an array of system wide leaders.
User[]	getLeaders(long communityID) Returns an Iterable of leaders for a specific community
User[]	getLeaders(long communityID, int startIndex, int numResults) Returns an Iterable of leaders for a specific community
long	getPointLevel(long userID) Returns the point level for a user system wide.
long	getPointLevel(long userID, long communityID) Returns the status level points for a user in regards to a specific community
StatusLevel[]	getPointStatusLevels() Returns an array of point based status levels in the system sorted by point range.
StatusLevel	getStatusLevel(long statusLevelID) Used to acquire a specific status level object from the system
StatusLevel	getStatusLevelByPoints(long points) Used to get a status level by a point value.
StatusLevelScenario	getStatusLevelScenarioByCode(java.lang.String code) Returns a StatusLevelScenario by its code.
StatusLevel	getUserStatusLevel(long userID) Returns the system wide status level for specific user, will return null if there is no status level for this user.
boolean	isStatusLevelsEnabled() Returns true if status levels are enabled in the system
void	setStatusLevelsEnabled(boolean enabled) 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(java.lang.String name,
                              java.lang.String imagePath,
                              int minPoints,
                              int maxPoints)
                              throws com.jivesoftware.community.StatusLevelAlreadyExistsException,
                                     com.jivesoftware.community.StatusLevelException

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

com.jivesoftware.community.StatusLevelException - if an illegal range is specified.

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

createStatusLevel

StatusLevel createStatusLevel(java.lang.String name,
                              java.lang.String imagePath,
                              long groupID)
                              throws com.jivesoftware.community.StatusLevelAlreadyExistsException,
                                     com.jivesoftware.community.StatusLevelException,
                                     GroupNotFoundException

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.

groupID - ID of the group to associate this status level with

Returns:

newly created status level object

Throws:

UnauthorizedException - if not system admin

com.jivesoftware.community.StatusLevelException - If this status level cannot be created.

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

GroupNotFoundException - If the specified group is not found.

deleteStatusLevel

void deleteStatusLevel(long statusLevelID)
                       throws com.jivesoftware.community.StatusLevelNotFoundException

Deletes a statusLevel level from the system

Parameters:

statusLevelID - ID of the statusLevel level to delete

Throws:

UnauthorizedException - if not system admin

com.jivesoftware.community.StatusLevelNotFoundException - If the id of the specified status level does not exist.

getGroupStatusLevels

StatusLevel[] getGroupStatusLevels()

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

Returns:

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

getPointStatusLevels

StatusLevel[] getPointStatusLevels()

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

Returns:

point range sorted array of StatusLevel objects

getLeaders

User[] getLeaders()

Returns an array of system wide leaders.

Returns:

Array of User objects for system wide leaders

getLeaders

User[] getLeaders(int startIndex,
                  int numResults)

Returns an array of system wide leaders.

Parameters:

startIndex - The starting point of the results.

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

Returns:

Array of User objects for system wide leaders

getLeaders

User[] getLeaders(long communityID)
                  throws CommunityNotFoundException

Returns an Iterable of leaders for a specific community

Parameters:

communityID - ID of the community to find leaders for.

Returns:

Array of User objects for a specific forum

Throws:

CommunityNotFoundException - Thrown if the community with the specified id does not exist.

getLeaders

User[] getLeaders(long communityID,
                  int startIndex,
                  int numResults)
                  throws CommunityNotFoundException

Returns an Iterable of leaders for a specific community

Parameters:

communityID - ID of the community to find leaders for

startIndex - The starting point of the leader results.

numResults - The number of results in the array.

Returns:

Iterable of User objects for a specific forum

Throws:

CommunityNotFoundException - Thrown if the community with the specified id does not exist.

getStatusLevel

StatusLevel getStatusLevel(long statusLevelID)
                           throws com.jivesoftware.community.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:

com.jivesoftware.community.StatusLevelNotFoundException - thrown if the object does not exist in the system

getUserStatusLevel

StatusLevel getUserStatusLevel(long userID)
                               throws UserNotFoundException

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:

userID - IDof the user to find the status level for

Returns:

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

Throws:

UserNotFoundException - Thrown if the user with the specified id does not exist.

setStatusLevelsEnabled

void setStatusLevelsEnabled(boolean enabled)

Sets whether status levels should be enabled in the system.

Parameters:

enabled - 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(long userID)
                   throws UserNotFoundException

Returns the point level for a user system wide.

Parameters:

userID - ID of the user to get status level points for

Returns:

how many status points the user has

Throws:

UserNotFoundException - Thrown if the user with the specified id does not exist.

getPointLevel

long getPointLevel(long userID,
                   long communityID)
                   throws UserNotFoundException,
                          CommunityNotFoundException

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

Parameters:

userID - ID of the user to get status level points for

communityID - ID of the community to filter by

Returns:

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

Throws:

CommunityNotFoundException - Thrown if the Community with the specified id does not exist.

UserNotFoundException - Thrown if the user with the specified id does not exist.

getGroupStatusLevel

StatusLevel getGroupStatusLevel(long groupID)
                                throws GroupNotFoundException

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:

groupID - ID of the group to find a status level for

Returns:

status level that is associated with group, else null

Throws:

GroupNotFoundException - Thrown if the group with the specified id does not exist.

addPoints

void addPoints(long userID,
               long communityID,
               long objectID,
               int objectType,
               long points,
               java.lang.String code)
               throws com.jivesoftware.community.NotFoundException

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:

userID - The ID of the user who is receiving points.

communityID - The ID of the community the points are added to.

objectID - The ID of 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.

objectType - The objectType of the object to add points for.

Throws:

com.jivesoftware.community.NotFoundException - Thrown if one of the ids for the specified object does not exist.

getAllStatusLevelScenarios

StatusLevelScenario[] getAllStatusLevelScenarios()

Returns all of the StatusLevelScenario objects.

Returns:

all of the 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(java.lang.String code)

Returns a StatusLevelScenario by its code.

Parameters:

code - The code of the StatusLevelScenario.

Returns:

The matching StatusLevelScenario.