Jive Forums API (5.5.20.2-oracle) Core Javadocs

com.jivesoftware.forum
Interface RewardManager


public interface RewardManager

Manages the reward points that users can trade back and forth when answerings questions. The author of each thread can transfer a variable number of points to any thread they create. Subsequently, they can award those points to whoever they feel makes the best responses in that thread. System administrators also have the ability to reward any number of points to any user.

This manager provides methods to transfer points to threads from users, and to reward the best posts in a thread with points. It also provies the ability to check the number of points that individual threads, messages, and users have.


Method Summary
 void addBankPoints(int numPoints)
          Allows administrators to add or substract an arbitrary number of reward points from all user's point banks.
 void addBankPoints(User user, int numPoints)
          Allows administrators to add or substract an arbitrary number of reward points from a user's point bank.
 int getBankPoints(User user)
          Returns the current number of reward points a user has.
 int getInitialBankPoints()
          Returns the number of bank points a user will start with.
 int getMaxBankPoints()
          Returns the max number of points that can accumulate in a bank account, or -1 if there is no max.
 int getMaxMessagePoints()
          Returns the maximum number of reward points that can be assigned to a message.
 int getMaxThreadPoints()
          Returns the maximum number of reward points that can be assigned to a thread.
 java.util.Iterator getPendingRewardThreads(User user)
          Returns the threads (ordered by modified date) that the user has assigned points to that haven't been fully rewarded out yet.
 int getPendingRewardThreadsCount(User user)
          Returns a count of the threads that the user has assigned points to that haven't been fully rewarded out yet.
 int getPoints(ForumMessage message)
          Returns the number of reward points that have been assigned to a message.
 int getPoints(ForumThread thread)
          Returns the number of reward points in a thread that are left to be distributed.
 int getPointsEarned(User user)
          Returns the total number of points that a user has earned across the entire system.
 int getPointsEarned(User user, Forum forum)
          Returns the total number of points the user has earned in a particular forum.
 int getPointsEarned(User user, ForumCategory category)
          Returns the total number of points the user has earned in a particular category.
 int getPointsRewarded(ForumThread thread)
          Returns the total number of points rewarded to messages in the thread.
 int getPointsRewarded(User user)
          Returns the total number of points that a user has ever rewarded.
 java.util.Iterator getTopUsers(int startIndex, int numResults)
          Returns an iterator for the top point earners in the entire system.
 java.util.Iterator getTopUsers(int startIndex, int numResults, Forum forum)
          Returns an iterator for the top point earners in a forum.
 java.util.Iterator getTopUsers(int startIndex, int numResults, ForumCategory category)
          Returns an iterator for the top point earners in a category.
 boolean isBankEnabled()
          Returns true if bank points are enabled.
 boolean isRewardsEnabled()
          Returns true if rewards are enabled, false otherwise.
 void rewardPoints(ForumMessage message, int numPoints)
          Rewards a message with points from the thread that the message belongs to.
 void setBankEnabled(boolean enabled)
          Toggles bank points to enabled or disabled.
 void setInitialBankPoints(int initialBankPoints)
          Sets the number of bank points a user will start with.
 void setMaxBankPoints(int maxBankPoints)
          Sets the max number of points that can accumulate in a bank account.
 void setMaxMessagePoints(int numPoints)
          Sets the maximum number of reward points that can be assigned to a message.
 void setMaxThreadPoints(int numPoints)
          Sets the maximum number of reward points that can be assigned to a thread.
 void setRewardsEnabled(boolean enabled)
          Enables or disables the rewards feature.
 void transferPoints(ForumThread thread, int numPoints)
          Transfers the specified number of points to the thread.
 

Method Detail

isRewardsEnabled

boolean isRewardsEnabled()
Returns true if rewards are enabled, false otherwise.

Returns:
true if rewards are enabled, false otherwise.

setRewardsEnabled

void setRewardsEnabled(boolean enabled)
                       throws UnauthorizedException
Enables or disables the rewards feature.

Parameters:
enabled - true to enable rewards, false otherwise.
Throws:
UnauthorizedException - if the user is not a system admin.

getMaxThreadPoints

int getMaxThreadPoints()
Returns the maximum number of reward points that can be assigned to a thread. By default, the value is -1, which means that there is no max.

Returns:
the max number of reward points that can be assigned to a thread, or -1 if there is no max.

setMaxThreadPoints

void setMaxThreadPoints(int numPoints)
                        throws UnauthorizedException
Sets the maximum number of reward points that can be assigned to a thread. By default, the value is -1, which means that there is no max.

Parameters:
numPoints - the max number of reward points that can be assigned to a thread, or -1 if there is no max.
Throws:
UnauthorizedException

getMaxMessagePoints

int getMaxMessagePoints()
Returns the maximum number of reward points that can be assigned to a message. By default, the value is -1, which means that there is no max.

Returns:
the max number of reward points that can be assigned to a message, or -1 if there is no max.

setMaxMessagePoints

void setMaxMessagePoints(int numPoints)
                         throws UnauthorizedException
Sets the maximum number of reward points that can be assigned to a message. By default, the value is -1, which means that there is no max.

Parameters:
numPoints - the max number of reward points that can be assigned to a message, or -1 if there is no max.
Throws:
UnauthorizedException

transferPoints

void transferPoints(ForumThread thread,
                    int numPoints)
                    throws UnauthorizedException,
                           RewardException
Transfers the specified number of points to the thread. Points will be drawn from the user account that started the thread. All of the following conditions must be met in order for this method to function: It is possible to use this method to transfer points back from a thread to a user if numPoints is a negative value. It is highly recommended that if you do allow points to be transferred back from a thread to a user, you only do so if there are no responses in the thread. This is a good compromise since it let's user's take back "mistaken" reward points, but also prevents the "bait and switch" of users assigning points to lure others into making responses and then taking away those points for future use.

Parameters:
thread - the thread to transfer points to.
numPoints - the number of points to transfer.
Throws:
UnauthorizedException - if not the user that started the thread or an admin.
RewardException

rewardPoints

void rewardPoints(ForumMessage message,
                  int numPoints)
                  throws UnauthorizedException,
                         RewardException
Rewards a message with points from the thread that the message belongs to. The user that created the message will also have the points added to their account. All of the following conditions must be met (or a RewardException is thrown):

Parameters:
message - the message receiving the reward.
numPoints - the number of points to reward the message with.
Throws:
UnauthorizedException - if not author of the thread the message is in, or an administrator.
RewardException - if one of the necessary conditions for this method to execute is not met.

getPoints

int getPoints(ForumThread thread)
Returns the number of reward points in a thread that are left to be distributed. The number will never exceed the value of getMaxThreadPoints() - getPointsRewarded(ForumThread).

Parameters:
thread - the thread.
Returns:
the number of points in a thread that are left to be distributed.

getPointsRewarded

int getPointsRewarded(ForumThread thread)
Returns the total number of points rewarded to messages in the thread. For example, if the user has rewarded two messages in the thread with 4 and 5 points, respectively, this method would return 9. The number will never exceed getMaxThreadPoints() - getPoints(ForumThread).

Parameters:
thread - the thread.
Returns:
the total number of points rewarded to messages in the thread.

getPoints

int getPoints(ForumMessage message)
Returns the number of reward points that have been assigned to a message. Assigning points to a message also gives those points to the user that created a message.

Parameters:
message - the message.
Returns:
the number of points a message has been assigned.

isBankEnabled

boolean isBankEnabled()
Returns true if bank points are enabled.

Returns:
true if bank points are enabled.

setBankEnabled

void setBankEnabled(boolean enabled)
                    throws UnauthorizedException
Toggles bank points to enabled or disabled.

Parameters:
enabled - true if bank points should be enabled; false otherwise.
Throws:
UnauthorizedException

getBankPoints

int getBankPoints(User user)
Returns the current number of reward points a user has. Users gain points when messages they authored are rewarded and lose points when they transfer points to threads they create.

Parameters:
user - the user.
Returns:
the number of points a user has.

addBankPoints

void addBankPoints(User user,
                   int numPoints)
                   throws UnauthorizedException
Allows administrators to add or substract an arbitrary number of reward points from a user's point bank. To remove points, simple pass in a negative point value. Note, the bank points for the user will never exceed the value returned by getMaxBankPoints() and will never be less than 0.

Parameters:
user - the user to give points to.
numPoints - the number of points to put in the user's bank, which can be negative.
Throws:
UnauthorizedException

addBankPoints

void addBankPoints(int numPoints)
                   throws UnauthorizedException
Allows administrators to add or substract an arbitrary number of reward points from all user's point banks. To remove points, simple pass in a negative point value. Note, the bank points for each user will never exceed the value returned by getMaxBankPoints() and will never be less than 0.

Parameters:
numPoints - the bank points value.
Throws:
UnauthorizedException - if not the system administrator.

getInitialBankPoints

int getInitialBankPoints()
Returns the number of bank points a user will start with.

Returns:
the initial bank points.

setInitialBankPoints

void setInitialBankPoints(int initialBankPoints)
                          throws UnauthorizedException
Sets the number of bank points a user will start with.

Parameters:
initialBankPoints - the initial bank points.
Throws:
UnauthorizedException - if not the system administrator.

getMaxBankPoints

int getMaxBankPoints()
Returns the max number of points that can accumulate in a bank account, or -1 if there is no max.

Returns:
the max size a bank account can grow to, or -1 if there is no limit.

setMaxBankPoints

void setMaxBankPoints(int maxBankPoints)
                      throws UnauthorizedException
Sets the max number of points that can accumulate in a bank account. The value -1 menas that there is no limit. When this value is set, all users' current bank points will be adjusted to not exceed the max. This change is irreversible, so care should be taken when adjusting this value.

Parameters:
maxBankPoints - the max size the bank account can grow to, or -1 if there is no limit.
Throws:
UnauthorizedException - if not the system administrator.

getPendingRewardThreadsCount

int getPendingRewardThreadsCount(User user)
Returns a count of the threads that the user has assigned points to that haven't been fully rewarded out yet. This is useful for showing a user the threads they may need to go back and look at to assign points to.

Parameters:
user - the user.
Returns:
the count of threads that a user has un-rewarded points in.

getPendingRewardThreads

java.util.Iterator getPendingRewardThreads(User user)
Returns the threads (ordered by modified date) that the user has assigned points to that haven't been fully rewarded out yet. This is useful for showing a user the threads that they may need to go back and look at to assign points in.

Parameters:
user - the user.
Returns:
a Iterator for the threads that a user has un-rewarded points in.

getPointsRewarded

int getPointsRewarded(User user)
Returns the total number of points that a user has ever rewarded. Highlighting this value may be a good idea for communities that use the reward system since it is a great way to encourage people to give out points (instead of hoarding them).

Points are not considered rewarded until they are actually transferred from a thread to

Parameters:
user - the user.
Returns:
the total number of points that a user has rewarded.

getPointsEarned

int getPointsEarned(User user)
Returns the total number of points that a user has earned across the entire system.

Parameters:
user - the user.
Returns:
the total number of points that a user has ever earned.

getPointsEarned

int getPointsEarned(User user,
                    ForumCategory category)
Returns the total number of points the user has earned in a particular category.

Parameters:
user - the user.
category - the category.
Returns:
the number of points the user has earned in the category.

getPointsEarned

int getPointsEarned(User user,
                    Forum forum)
Returns the total number of points the user has earned in a particular forum.

Parameters:
user - the user.
forum - the forum.
Returns:
the number of points the user has earned in the forum.

getTopUsers

java.util.Iterator getTopUsers(int startIndex,
                               int numResults)
Returns an iterator for the top point earners in the entire system.

Parameters:
startIndex - the starting index in the results list (0 to start at the beginning of the list).
numResults - the number of results to return.
Returns:
an iterator for the top point earners in the system.

getTopUsers

java.util.Iterator getTopUsers(int startIndex,
                               int numResults,
                               ForumCategory category)
Returns an iterator for the top point earners in a category.

Parameters:
startIndex - the starting index in the results list (0 to start at the beginning of the list).
numResults - the number of results to return.
category - the category.
Returns:
an iterator for the top point earners in a category.

getTopUsers

java.util.Iterator getTopUsers(int startIndex,
                               int numResults,
                               Forum forum)
Returns an iterator for the top point earners in a forum.

Parameters:
startIndex - the starting index in the results list (0 to start at the beginning of the list).
numResults - the number of results to return.
forum - the forum.
Returns:
an iterator for the top point earners in a forum.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.