Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum
Interface RatingManager

All Known Implementing Classes:
DbRatingManager, RatingManagerProxy

public interface RatingManager

Provides optional rating of forum messages. This feature is optional in that other Jive Forums classes do not call this API. Instead, the UI layer must explicitly check to see if a message is rated or unrated by any particular user and display rating options as appropriate.

An example usage to give a rating to a forum message is as follows:

 RatingManager manager = factory.getRatingManager();
 Iterator ratings = manager.getAvailableRatings();
 ... (user chooses via a webpage or another mechanism a specific rating for a message)
 Rating rating = manager.getRating(3); // the chosen rating of the user with a score of 3
 ForumMessage message = factory.getMessage(messageID);
 manager.addRating(user, message, rating);
 ...
 

Since:
4.0
See Also:
Rating

Method Summary
 void addRating(User user, ForumMessage message, Rating rating)
          Add a rating to the forum message.
 void addRating(User user, ForumThread thread, Rating rating)
          Add a rating to the forum thread.
 Rating createRating(int score, java.lang.String description)
          Create a new rating with the specified attributes.
 int getAvailableRatingCount()
          Returns the count of currently available ratings.
 java.util.Iterator getAvailableRatings()
          Returns an iterator of Rating objects that list all the available ratings.
 double getMeanRating(ForumMessage message)
          A convenience method which returns a geometric mean average of all the ratings given to the forum message.
 double getMeanRating(ForumThread thread)
          A convenience method which returns a geometric mean average of all the ratings given to the forum thread.
 double getMeanRating(long messageID)
          A convenience method which returns a geometric mean average of all the ratings given to the forum message.
 Rating getRating(User user, ForumMessage message)
          Returns the rating associated with the user, or null if this user hasn't rated the forum message.
 Rating getRating(User user, ForumThread thread)
          Returns the rating associated with the user, or null if this user hasn't rated the forum thread.
 int getRatingCount(ForumMessage message)
          Returns the total number of ratings given to the forum message.
 int getRatingCount(ForumThread thread)
          Returns the total number of ratings given to the forum thread.
 Rating getRatingFromScore(int score)
          Retrieve the rating with the specified score.
 java.util.Iterator getRatings(ForumMessage message)
          Returns an Iterator of all the ratings given to the forum message.
 java.util.Iterator getRatings(ForumThread thread)
          Returns an Iterator of all the ratings given to the forum thread.
 boolean hasRated(User user, ForumMessage message)
          Returns whether the user has rated the forum message or not.
 boolean hasRated(User user, ForumThread thread)
          Returns whether the user has rated the forum thread or not.
 boolean isRatingsEnabled()
          Returns true if the rating feature is turned on.
 void removeRating(Rating rating)
          Remove the specified rating from the list of currently available ratings.
 void setRatingsEnabled(boolean ratingsEnabled)
          Enables or disables the ratings feature.
 

Method Detail

isRatingsEnabled

boolean isRatingsEnabled()
Returns true if the rating feature is turned on. When ratings are disabled, other methods serve as no-ops.

Returns:
true if the ratings are enabled

setRatingsEnabled

void setRatingsEnabled(boolean ratingsEnabled)
                       throws UnauthorizedException
Enables or disables the ratings feature. When ratings are disabled, other methods serve as no-ops.

Parameters:
ratingsEnabled - true to enable the rating feature, false to disable
Throws:
UnauthorizedException - if not a system administrator

getAvailableRatings

java.util.Iterator getAvailableRatings()
Returns an iterator of Rating objects that list all the available ratings. The returned list will be sorted from lowest rating to high rating.

Returns:
an iterator of all available ratings

getAvailableRatingCount

int getAvailableRatingCount()
Returns the count of currently available ratings.

Returns:
a count of currently available ratings

getRatingFromScore

Rating getRatingFromScore(int score)
Retrieve the rating with the specified score.

Parameters:
score - the score of the rating to retrieve
Returns:
the corresponding rating, or null if no rating matches

createRating

Rating createRating(int score,
                    java.lang.String description)
                    throws UnauthorizedException
Create a new rating with the specified attributes. Only positive integers are allowed for the score, 0 or negative integers will cause an IllegalArgumentException to be thrown. If the score is already taken an IllegalArgumentException will be thrown.

Parameters:
score - the score or rating level for the new rating
description - the description of the new rating
Returns:
a new Rating object
Throws:
UnauthorizedException - if not a system administrator

removeRating

void removeRating(Rating rating)
                  throws UnauthorizedException
Remove the specified rating from the list of currently available ratings.

Parameters:
rating - the Rating to remove
Throws:
UnauthorizedException - if not a system administrator

getRatings

java.util.Iterator getRatings(ForumMessage message)
Returns an Iterator of all the ratings given to the forum message.

Parameters:
message - the forum message to return ratings for
Returns:
an Iterator of all the ratings given to the forum message

getRatings

java.util.Iterator getRatings(ForumThread thread)
Returns an Iterator of all the ratings given to the forum thread. The ratings returned only apply to the thread itself - they do not include ratings for individual messages in the thread.

Parameters:
thread - the forum thread to return ratings for
Returns:
an Iterator of all the ratings given to the forum thread

getRatingCount

int getRatingCount(ForumMessage message)
Returns the total number of ratings given to the forum message.

Parameters:
message - the forum message to return a rating count for
Returns:
the total number of ratings given to the forum message.

getRatingCount

int getRatingCount(ForumThread thread)
Returns the total number of ratings given to the forum thread. The count returned returned only applies to the thread itself - it does not include ratings for individual messages in the thread.

Parameters:
thread - the forum thread to return a rating count for
Returns:
the total number of ratings given to the forum thread.

getMeanRating

double getMeanRating(long messageID)
A convenience method which returns a geometric mean average of all the ratings given to the forum message.

Returns:
a geometric mean average of all the ratings given to the forum message.

getMeanRating

double getMeanRating(ForumMessage message)
A convenience method which returns a geometric mean average of all the ratings given to the forum message.

Returns:
a geometric mean average of all the ratings given to the forum message.

getMeanRating

double getMeanRating(ForumThread thread)
A convenience method which returns a geometric mean average of all the ratings given to the forum thread. The mean average returned returned only applies to the thread itself - it does not include ratings for individual messages in the thread.

Returns:
a geometric mean average of all the ratings given to the forum thread.

hasRated

boolean hasRated(User user,
                 ForumMessage message)
Returns whether the user has rated the forum message or not. This method will always return false if the user is anonymous.

Parameters:
user - the user to check
message - the forum message to check
Returns:
true is the user associated with the user has rated the forum message, false otherwise. If the user is anonymous (null) this method will always return false.

hasRated

boolean hasRated(User user,
                 ForumThread thread)
Returns whether the user has rated the forum thread or not. This method will always return false if the user is anonymous.

Parameters:
user - the user to check
thread - the forum thread to check
Returns:
true is the user associated with the user has rated the forum thread, false otherwise. If the user is anonymous (null) this method will always return false.

getRating

Rating getRating(User user,
                 ForumMessage message)
Returns the rating associated with the user, or null if this user hasn't rated the forum message. If the user is null (anonymous) this method will return null.

Parameters:
user - the user to check
message - the forum message to check
Returns:
the rating the user has given the forum message, or null if the user has not rated the forum message or the user is anonymous.

getRating

Rating getRating(User user,
                 ForumThread thread)
Returns the rating associated with the user, or null if this user hasn't rated the forum thread. If the user is null (anonymous) this method will return null.

Parameters:
user - the user to check
thread - the forum thread to check
Returns:
the rating the user has given the forum thread, or null if the user has not rated the forum thread or the user is anonymous.

addRating

void addRating(User user,
               ForumMessage message,
               Rating rating)
               throws UnauthorizedException
Add a rating to the forum message. If the user has already rated, this rating will replace the previous rating. If the user is null (anonymous) this rating will be added to the ratings for the forum message.

The author of the forum message cannot rate their own message.

Parameters:
user - the user rating the forum message
message - the forum message to add the rating to
rating - the rating the user wants to give to the forum message
Throws:
UnauthorizedException - if user does not have permissions

addRating

void addRating(User user,
               ForumThread thread,
               Rating rating)
               throws UnauthorizedException
Add a rating to the forum thread. If the user has already rated, this rating will replace the previous rating. If the user is null (anonymous) this rating will be added to the ratings for the forum thread.

Parameters:
user - the user rating the forum thread
thread - the forum thread to add the rating to
rating - the rating the user wants to give to the forum thread
Throws:
UnauthorizedException - if user does not have permissions

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.