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.
WSStatusLevel	createStatusLevel(java.lang.String name, java.lang.String imagePath, int minPoints, int maxPoints) Creates a new points based StatusLevel.
WSStatusLevel	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
WSStatusLevelScenario[]	getAllStatusLevelScenarios() Returns all of the WSStatusLevelScenario objects.
WSStatusLevel	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.
WSStatusLevel[]	getGroupStatusLevels() Returns an array of all group based status levels in the system.
WSUser[]	getLeaders() Returns an array of system wide leaders.
WSUser[]	getLeaders(int startIndex, int numResults) Returns an array of system wide leaders.
WSUser[]	getLeaders(long communityID) Returns an Iterable of leaders for a specific community
WSUser[]	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
WSStatusLevel[]	getPointStatusLevels() Returns an array of point based status levels in the system sorted by point range.
WSStatusLevel	getStatusLevel(long statusLevelID) Used to acquire a specific status level object from the system
WSStatusLevel	getStatusLevelByPoints(long points) Used to get a status level by a point value.
WSStatusLevelScenario	getStatusLevelScenarioByCode(java.lang.String code) Returns a WSStatusLevelScenario by its code.
WSStatusLevel	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 statusLevelsEnabled) Sets whether status levels should be enabled in the system.
void	updateStatusLevelScenario(WSStatusLevelScenario scenario) Update the points and whether or not this scenario is included in status level results.

Method Detail

createStatusLevel

WSStatusLevel 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

WSStatusLevel 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

WSStatusLevel[] 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

WSStatusLevel[] 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

WSUser[] getLeaders()

Returns an array of system wide leaders.

Returns:

Array of WSUser objects for system wide leaders

getLeaders

WSUser[] 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 WSUser objects for system wide leaders

getLeaders

WSUser[] 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 WSUser objects for a specific forum

Throws:

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

getLeaders

WSUser[] 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 WSUser objects for a specific forum

Throws:

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

getStatusLevel

WSStatusLevel 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

getUserStatusLevel

WSStatusLevel 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 statusLevelsEnabled)

Sets whether status levels should be enabled in the system.

Parameters:

statusLevelsEnabled - true if status levels are statusLevelsEnabled, 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

WSStatusLevel 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

WSStatusLevel 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

WSStatusLevelScenario[] getAllStatusLevelScenarios()

Returns all of the WSStatusLevelScenario objects.

Returns:

all of the WSStatusLevelScenario objects.

updateStatusLevelScenario

void updateStatusLevelScenario(WSStatusLevelScenario 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

WSStatusLevelScenario getStatusLevelScenarioByCode(java.lang.String code)

Returns a WSStatusLevelScenario by its code.

Parameters:

code - The code of the StatusLevelScenario.

Returns:

The matching StatusLevelScenario.