Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum.database
Class DbRewardManager

java.lang.Object
  extended by com.jivesoftware.forum.database.DbRewardManager
All Implemented Interfaces:
ForumListener, MessageListener, ThreadListener, RewardManager

public class DbRewardManager
extends java.lang.Object
implements RewardManager, ForumListener, ThreadListener, MessageListener

Database implementation of the RewardManager interface. A user's point total is stored the jiveUserReward database table. Points values are also maintained in the thread and message tables. Although storing values in all three places isn't ideal in a relational sense, it's necessary to make speed tolerable.

For auditing purposes, points awards are recorded in a special database table which tracks the ID of the user receiving the points, the amount of points awarded, and a timestamp. Optionally, the thread and message IDs are stored. This schema allows us to track normal point awards as well as when administrators assigning arbitrary point values.

To customize the max number of reward points that can be set for a thread, adjust the Jive property rewards.maxPoints.


Constructor Summary
DbRewardManager()
           
 
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.
 void forumAdded(ForumEvent event)
          Fired when a forum has been added to the system.
 void forumDeleted(ForumEvent event)
          Fired when a forum is about to be deleted from the system.
 void forumMerged(ForumEvent event)
          Fired when a forum is merged into another forum.
 void forumModified(ForumEvent event)
          Fired when a forum is modified.
 void forumMoved(ForumEvent event)
          Fired when a forum has been moved from one category to another.
 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 messageAdded(MessageEvent event)
          Fired when a message has been added to the system.
 void messageDeleted(MessageEvent event)
          Fired when a message is about to be deleted from the system.
 void messageModerationModified(MessageEvent event)
          Fired when the moderation value of a message has been changed.
 void messageModified(MessageEvent event)
          Fired when portions of a message have been modified.
 void messageMoved(MessageEvent event)
          Fired when a message is moved to another thread.
 void messageRated(MessageEvent event)
          Fired when a message has been rated.
 void rewardPoints(ForumMessage message, int numPoints)
          Rewards a message with points from the thread that the message belongs to.
 void setBankEnabled(boolean bankEnabled)
          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 threadAdded(ThreadEvent event)
          Fired when a thread has been added to the system.
 void threadDeleted(ThreadEvent event)
          Fired when a thread is about to be deleted from the system.
 void threadModerationModified(ThreadEvent event)
          Fired when the moderation value of a thread has been changed.
 void threadMoved(ThreadEvent event)
          Fired when a thread is moved from one foru to another.
 void threadRated(ThreadEvent event)
          Fired when the thread has been rated.
 void transferPoints(ForumThread thread, int numPoints)
          Transfers the specified number of points to the thread.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DbRewardManager

public DbRewardManager()
Method Detail

isRewardsEnabled

public boolean isRewardsEnabled()
Description copied from interface: RewardManager
Returns true if rewards are enabled, false otherwise.

Specified by:
isRewardsEnabled in interface RewardManager
Returns:
true if rewards are enabled, false otherwise.

setRewardsEnabled

public void setRewardsEnabled(boolean enabled)
Description copied from interface: RewardManager
Enables or disables the rewards feature.

Specified by:
setRewardsEnabled in interface RewardManager
Parameters:
enabled - true to enable rewards, false otherwise.

getMaxThreadPoints

public int getMaxThreadPoints()
Description copied from interface: RewardManager
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.

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

setMaxThreadPoints

public void setMaxThreadPoints(int numPoints)
Description copied from interface: RewardManager
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.

Specified by:
setMaxThreadPoints in interface RewardManager
Parameters:
numPoints - the max number of reward points that can be assigned to a thread, or -1 if there is no max.

getMaxMessagePoints

public int getMaxMessagePoints()
Description copied from interface: RewardManager
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.

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

setMaxMessagePoints

public void setMaxMessagePoints(int numPoints)
                         throws UnauthorizedException
Description copied from interface: RewardManager
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.

Specified by:
setMaxMessagePoints in interface RewardManager
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

public void transferPoints(ForumThread thread,
                           int numPoints)
                    throws RewardException
Description copied from interface: RewardManager
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.

Specified by:
transferPoints in interface RewardManager
Parameters:
thread - the thread to transfer points to.
numPoints - the number of points to transfer.
Throws:
RewardException

rewardPoints

public void rewardPoints(ForumMessage message,
                         int numPoints)
                  throws RewardException
Description copied from interface: RewardManager
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):

Specified by:
rewardPoints in interface RewardManager
Parameters:
message - the message receiving the reward.
numPoints - the number of points to reward the message with.
Throws:
RewardException - if one of the necessary conditions for this method to execute is not met.

getPoints

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

Specified by:
getPoints in interface RewardManager
Parameters:
thread - the thread.
Returns:
the number of points in a thread that are left to be distributed.

getPointsRewarded

public int getPointsRewarded(ForumThread thread)
Description copied from interface: RewardManager
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 RewardManager.getMaxThreadPoints() - RewardManager.getPoints(ForumThread).

Specified by:
getPointsRewarded in interface RewardManager
Parameters:
thread - the thread.
Returns:
the total number of points rewarded to messages in the thread.

getPoints

public int getPoints(ForumMessage message)
Description copied from interface: RewardManager
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.

Specified by:
getPoints in interface RewardManager
Parameters:
message - the message.
Returns:
the number of points a message has been assigned.

isBankEnabled

public boolean isBankEnabled()
Description copied from interface: RewardManager
Returns true if bank points are enabled.

Specified by:
isBankEnabled in interface RewardManager
Returns:
true if bank points are enabled.

setBankEnabled

public void setBankEnabled(boolean bankEnabled)
                    throws UnauthorizedException
Description copied from interface: RewardManager
Toggles bank points to enabled or disabled.

Specified by:
setBankEnabled in interface RewardManager
Parameters:
bankEnabled - true if bank points should be enabled; false otherwise.
Throws:
UnauthorizedException

getBankPoints

public int getBankPoints(User user)
Description copied from interface: RewardManager
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.

Specified by:
getBankPoints in interface RewardManager
Parameters:
user - the user.
Returns:
the number of points a user has.

addBankPoints

public void addBankPoints(User user,
                          int numPoints)
Description copied from interface: RewardManager
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 RewardManager.getMaxBankPoints() and will never be less than 0.

Specified by:
addBankPoints in interface RewardManager
Parameters:
user - the user to give points to.
numPoints - the number of points to put in the user's bank, which can be negative.

addBankPoints

public void addBankPoints(int numPoints)
                   throws UnauthorizedException
Description copied from interface: RewardManager
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 RewardManager.getMaxBankPoints() and will never be less than 0.

Specified by:
addBankPoints in interface RewardManager
Parameters:
numPoints - the bank points value.
Throws:
UnauthorizedException - if not the system administrator.

getInitialBankPoints

public int getInitialBankPoints()
Description copied from interface: RewardManager
Returns the number of bank points a user will start with.

Specified by:
getInitialBankPoints in interface RewardManager
Returns:
the initial bank points.

setInitialBankPoints

public void setInitialBankPoints(int initialBankPoints)
Description copied from interface: RewardManager
Sets the number of bank points a user will start with.

Specified by:
setInitialBankPoints in interface RewardManager
Parameters:
initialBankPoints - the initial bank points.

getMaxBankPoints

public int getMaxBankPoints()
Description copied from interface: RewardManager
Returns the max number of points that can accumulate in a bank account, or -1 if there is no max.

Specified by:
getMaxBankPoints in interface RewardManager
Returns:
the max size a bank account can grow to, or -1 if there is no limit.

setMaxBankPoints

public void setMaxBankPoints(int maxBankPoints)
                      throws UnauthorizedException
Description copied from interface: RewardManager
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.

Specified by:
setMaxBankPoints in interface RewardManager
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.

getPointsRewarded

public int getPointsRewarded(User user)
Description copied from interface: RewardManager
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

Specified by:
getPointsRewarded in interface RewardManager
Parameters:
user - the user.
Returns:
the total number of points that a user has rewarded.

getPointsEarned

public int getPointsEarned(User user)
Description copied from interface: RewardManager
Returns the total number of points that a user has earned across the entire system.

Specified by:
getPointsEarned in interface RewardManager
Parameters:
user - the user.
Returns:
the total number of points that a user has ever earned.

getPointsEarned

public int getPointsEarned(User user,
                           Forum forum)
Description copied from interface: RewardManager
Returns the total number of points the user has earned in a particular forum.

Specified by:
getPointsEarned in interface RewardManager
Parameters:
user - the user.
forum - the forum.
Returns:
the number of points the user has earned in the forum.

getPointsEarned

public int getPointsEarned(User user,
                           ForumCategory category)
Description copied from interface: RewardManager
Returns the total number of points the user has earned in a particular category.

Specified by:
getPointsEarned in interface RewardManager
Parameters:
user - the user.
category - the category.
Returns:
the number of points the user has earned in the category.

getTopUsers

public java.util.Iterator getTopUsers(int startIndex,
                                      int numResults)
Description copied from interface: RewardManager
Returns an iterator for the top point earners in the entire system.

Specified by:
getTopUsers in interface RewardManager
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

public java.util.Iterator getTopUsers(int startIndex,
                                      int numResults,
                                      ForumCategory category)
Description copied from interface: RewardManager
Returns an iterator for the top point earners in a category.

Specified by:
getTopUsers in interface RewardManager
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

public java.util.Iterator getTopUsers(int startIndex,
                                      int numResults,
                                      Forum forum)
Description copied from interface: RewardManager
Returns an iterator for the top point earners in a forum.

Specified by:
getTopUsers in interface RewardManager
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.

getPendingRewardThreadsCount

public int getPendingRewardThreadsCount(User user)
Description copied from interface: RewardManager
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.

Specified by:
getPendingRewardThreadsCount in interface RewardManager
Parameters:
user - the user.
Returns:
the count of threads that a user has un-rewarded points in.

getPendingRewardThreads

public java.util.Iterator getPendingRewardThreads(User user)
Description copied from interface: RewardManager
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.

Specified by:
getPendingRewardThreads in interface RewardManager
Parameters:
user - the user.
Returns:
a Iterator for the threads that a user has un-rewarded points in.

forumAdded

public void forumAdded(ForumEvent event)
Description copied from interface: ForumListener
Fired when a forum has been added to the system.

Specified by:
forumAdded in interface ForumListener
Parameters:
event - the event object.

forumDeleted

public void forumDeleted(ForumEvent event)
Description copied from interface: ForumListener
Fired when a forum is about to be deleted from the system. This event will be fired when an individual forum is deleted or when the forum's category is deleted. Because various code pieces may depend on this event for performing cleanup tasks, it's guaranteed that this method will be called before the forum is deleted from the database.

Specified by:
forumDeleted in interface ForumListener
Parameters:
event - the event object.

forumMoved

public void forumMoved(ForumEvent event)
Description copied from interface: ForumListener
Fired when a forum has been moved from one category to another.

Specified by:
forumMoved in interface ForumListener
Parameters:
event - the event object.

forumModified

public void forumModified(ForumEvent event)
Description copied from interface: ForumListener
Fired when a forum is modified.

Specified by:
forumModified in interface ForumListener
Parameters:
event - the event object.

forumMerged

public void forumMerged(ForumEvent event)
Description copied from interface: ForumListener
Fired when a forum is merged into another forum.

Specified by:
forumMerged in interface ForumListener
Parameters:
event - the event object.

threadAdded

public void threadAdded(ThreadEvent event)
Description copied from interface: ThreadListener
Fired when a thread has been added to the system.

Specified by:
threadAdded in interface ThreadListener
Parameters:
event - the event object.

threadDeleted

public void threadDeleted(ThreadEvent event)
Description copied from interface: ThreadListener
Fired when a thread is about to be deleted from the system. This event will only be fired when an individual thread is deleted; it is not fired when the forum that contains the thread is deleted. Because various code pieces may depend on this event for performing cleanup tasks, it's guaranteed that this method will be called before the thread is deleted from the database.

Specified by:
threadDeleted in interface ThreadListener
Parameters:
event - the event object.

threadMoved

public void threadMoved(ThreadEvent event)
Description copied from interface: ThreadListener
Fired when a thread is moved from one foru to another.

Specified by:
threadMoved in interface ThreadListener
Parameters:
event - the event object.

threadModerationModified

public void threadModerationModified(ThreadEvent event)
Description copied from interface: ThreadListener
Fired when the moderation value of a thread has been changed.

Specified by:
threadModerationModified in interface ThreadListener
Parameters:
event - the event object.

threadRated

public void threadRated(ThreadEvent event)
Description copied from interface: ThreadListener
Fired when the thread has been rated.

Specified by:
threadRated in interface ThreadListener
Parameters:
event - the event object.

messageAdded

public void messageAdded(MessageEvent event)
Description copied from interface: MessageListener
Fired when a message has been added to the system. Care should be taken with this event type since a message being added may need to go through a moderation process before it becomes visible in a forum. Therefore, actions that should only be triggered after moderation has taken place should use the message moderation modified event type instead.

Specified by:
messageAdded in interface MessageListener
Parameters:
event - the event object.

messageDeleted

public void messageDeleted(MessageEvent event)
Description copied from interface: MessageListener
Fired when a message is about to be deleted from the system. This event will only be fired when an individual message is deleted; it is not fired when the thread or forum that contains the message is deleted. Because various code pieces may depend on this event for performing cleanup tasks, it's guaranteed that this method will be called before the message is deleted from the database.

Specified by:
messageDeleted in interface MessageListener
Parameters:
event - the event object.

messageModified

public void messageModified(MessageEvent event)
Description copied from interface: MessageListener
Fired when portions of a message have been modified.

Specified by:
messageModified in interface MessageListener
Parameters:
event - the event object.

messageModerationModified

public void messageModerationModified(MessageEvent event)
Description copied from interface: MessageListener
Fired when the moderation value of a message has been changed.

Specified by:
messageModerationModified in interface MessageListener
Parameters:
event - the event object.

messageRated

public void messageRated(MessageEvent event)
Description copied from interface: MessageListener
Fired when a message has been rated.

Specified by:
messageRated in interface MessageListener
Parameters:
event - the event object.

messageMoved

public void messageMoved(MessageEvent event)
Description copied from interface: MessageListener
Fired when a message is moved to another thread. This happens when a thread is branched such that a message and its children become a new thread.

Specified by:
messageMoved in interface MessageListener
Parameters:
event - the event object.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.