com.jivesoftware.community
Interface RatingManager

All Superinterfaces:

JiveManager

public interface RatingManager
extends JiveManager

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

An example usage to give a rating to a JiveContentObject is as follows:

 RatingManager manager = factory.getRatingManager();
 Iterable ratings = manager.getAvailableRatings();
 ... (user chooses via a webpage or another mechanism a specific rating for a JiveContentObject)
 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);
 ...
 

See Also:

Rating

Method Summary

void	addRating(User user, JiveObject contentObject, Rating rating) Add a rating to the JiveContentObject.
boolean	canRate(User user, JiveObject contentObject) Returns whether the user can rate the JiveContentObject or not.
Rating	createRating(int score, String description) Create a new rating with the specified attributes.
void	deleteUserRatings(User user) Remove all ratings associated with the given user.
int	getAvailableRatingCount() Returns the count of currently available ratings.
Iterable<Rating>	getAvailableRatings() Returns an iterable of Rating objects that list all the available ratings.
double	getMeanRating(JiveObject contentObject) A convenience method which returns a geometric mean average of all the ratings given to the JiveContentObject.
Rating	getRating(User user, JiveObject contentObject) Returns the rating associated with the user, or null if this user hasn't rated the JiveContentObject.
int	getRatingCount(JiveObject contentObject) Returns the total number of ratings given to the JiveContentObject.
Rating	getRatingFromScore(int score) Retrieve the rating with the specified score.
Iterable<Rating>	getRatings(JiveObject contentObject) Returns an Iterable of all the ratings given to the JiveContentObject.
boolean	hasRated(User user, JiveObject contentObject) Returns whether the user has rated the JiveContentObject or not.
boolean	isRatingsEnabled() Returns true if the rating feature is turned on.
void	removeAllRatings(JiveObject contentObject) Remove all ratings from the specified content object
void	removeRating(Rating rating) Remove the specified rating from the list of currently available ratings.
void	removeRating(User user, JiveObject contentObject) Removes a rating to the JiveContentObject.
void	setRatingsEnabled(boolean ratingsEnabled) Enables or disables the ratings feature.

Methods inherited from interface com.jivesoftware.community.JiveManager

destroy

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

Iterable<Rating> getAvailableRatings()

Returns an iterable of Rating objects that list all the available ratings. The returned list will be sorted from lowest rating to high rating.

Returns:

an iterable 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,
                    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

deleteUserRatings

void deleteUserRatings(User user)
                       throws UnauthorizedException

Remove all ratings associated with the given user.

Parameters:

user - the User associated with the ratings being deleted.

Throws:

UnauthorizedException - if not a system administrator or user administrator

getRatings

Iterable<Rating> getRatings(JiveObject contentObject)

Returns an Iterable of all the ratings given to the JiveContentObject.

Parameters:

contentObject - the JiveContentObject to return ratings for

Returns:

an Iterable of all the ratings given to the JiveContentObject

getRatingCount

int getRatingCount(JiveObject contentObject)

Returns the total number of ratings given to the JiveContentObject.

Parameters:

contentObject - the JiveContentObject to return a rating count for

Returns:

the total number of ratings given to the JiveContentObject.

getMeanRating

double getMeanRating(JiveObject contentObject)

A convenience method which returns a geometric mean average of all the ratings given to the JiveContentObject.

Parameters:

contentObject - the JiveContentObject to return a mean rating for

Returns:

a geometric mean average of all the ratings given to the JiveContentObject.

canRate

boolean canRate(User user,
                JiveObject contentObject)

Returns whether the user can rate the JiveContentObject or not.

Parameters:

user - the user to check

contentObject - the JiveContentObject to check

Returns:

true is the user can rate the JiveContentObject, false otherwise.

hasRated

boolean hasRated(User user,
                 JiveObject contentObject)

Returns whether the user has rated the JiveContentObject or not. This method will always return false if the user is anonymous.

Parameters:

user - the user to check

contentObject - the JiveContentObject to check

Returns:

true is the user associated with the user has rated the JiveContentObject, false otherwise. If the user is anonymous (null) this method will always return false.

getRating

Rating getRating(User user,
                 JiveObject contentObject)

Returns the rating associated with the user, or null if this user hasn't rated the JiveContentObject. If the user is null (anonymous) this method will return null.

Parameters:

user - the user to check

contentObject - the JiveContentObject to check

Returns:

the rating the user has given the JiveContentObject, or null if the user has not rated the JiveContentObject or the user is anonymous.

addRating

void addRating(User user,
               JiveObject contentObject,
               Rating rating)
               throws UnauthorizedException

Add a rating to the JiveContentObject. 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 JiveContentObject.

The author of the JiveContentObject cannot rate their own content.

Parameters:

user - the user rating the JiveContentObject

contentObject - the JiveContentObject to add the rating to

rating - the rating the user wants to give to the JiveContentObject

Throws:

UnauthorizedException - if user does not have permissions

removeRating

void removeRating(User user,
                  JiveObject contentObject)
                  throws UnauthorizedException

Removes a rating to the JiveContentObject.

Parameters:

user - the user rating the JiveContentObject

contentObject - the JiveContentObject to remove the rating from

Throws:

UnauthorizedException - if not a system administrator

removeAllRatings

void removeAllRatings(JiveObject contentObject)
                      throws UnauthorizedException

Remove all ratings from the specified content object

Parameters:

contentObject - the JiveContentObject to remove ratings from

Throws:

UnauthorizedException - if not a system administrator