com.jivesoftware.community.webservices
Interface RatingsService

public interface RatingsService

Method Summary

void	addRating(long userID, int objectType, long objectID, int ratingScore) Add a rating to the JiveContentObject.
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.
Rating[]	getAvailableRatings() Returns an iterable of Rating objects that list all the available ratings.
double	getMeanRating(int objectType, long objectID) A convenience method which returns a geometric mean average of all the ratings given to the JiveContentObject.
Rating	getRating(long userID, int objectType, long objectID) Returns the rating associated with the user, or null if this user hasn't rated the JiveContentObject.
int	getRatingCount(int objectType, long objectID) Returns the total number of ratings given to the JiveContentObject.
Rating	getRatingFromScore(int score) Retrieve the rating with the specified score.
Rating[]	getRatings(int objectType, long objectID) Returns an Iterable of all the ratings given to the JiveContentObject.
boolean	hasRated(long userID, int objectType, long objectID) Returns whether the user has rated the JiveContentObject or not.
boolean	isRatingsEnabled() Returns true if the rating feature is turned on.
void	removeRating(int score) 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)

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

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,
                    java.lang.String description)

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(int score)

Remove the specified rating from the list of currently available ratings.

Parameters:

score - of the Rating to remove

Throws:

UnauthorizedException - if not a system administrator

getRatings

Rating[] getRatings(int objectType,
                    long objectID)
                    throws com.jivesoftware.community.NotFoundException

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

Parameters:

objectType - the JiveObject.getObjectType() ()} to return ratings for

objectID - the JiveObject.getID() ()} to return ratings for

Returns:

an Iterable of all the ratings given to the JiveContentObject

Throws:

com.jivesoftware.community.NotFoundException - if object not found

getRatingCount

int getRatingCount(int objectType,
                   long objectID)
                   throws com.jivesoftware.community.NotFoundException

Returns the total number of ratings given to the JiveContentObject.

Parameters:

objectType - the JiveObject.getObjectType() ()} to return ratings for

objectID - the JiveObject.getID() ()} to return ratings for

Returns:

the total number of ratings given to the JiveContentObject.

Throws:

com.jivesoftware.community.NotFoundException - if object not found

getMeanRating

double getMeanRating(int objectType,
                     long objectID)
                     throws com.jivesoftware.community.NotFoundException

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

Parameters:

objectType - the JiveObject.getObjectType() ()} to return ratings for

objectID - the JiveObject.getID() ()} to return ratings for

Returns:

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

Throws:

com.jivesoftware.community.NotFoundException - if object not found

hasRated

boolean hasRated(long userID,
                 int objectType,
                 long objectID)
                 throws com.jivesoftware.community.NotFoundException

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

Parameters:

userID - of the user to check

objectType - the JiveObject.getObjectType() ()} to return ratings for

objectID - the JiveObject.getID() ()} to return ratings for

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.

Throws:

com.jivesoftware.community.NotFoundException - if object not found

getRating

Rating getRating(long userID,
                 int objectType,
                 long objectID)
                 throws com.jivesoftware.community.NotFoundException

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:

userID - of the user to check

objectType - the JiveObject.getObjectType() ()} to return ratings for

objectID - the JiveObject.getID() ()} to return ratings for

Returns:

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

Throws:

com.jivesoftware.community.NotFoundException - if content object or user not found

addRating

void addRating(long userID,
               int objectType,
               long objectID,
               int ratingScore)
               throws com.jivesoftware.community.NotFoundException,
                      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:

userID - the user rating the JiveContentObject

objectType - the JiveObject.getObjectType() ()} to return ratings for

objectID - the JiveObject.getID() ()} to return ratings for

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

Throws:

UnauthorizedException - if user does not have permissions

com.jivesoftware.community.NotFoundException - if content object or user not found