de.uka.ipd.consensus.foundation.rating
Interface RatingManager

All Superinterfaces:

ConsensusFoundationModule

All Known Implementing Classes:

SQLRatingManagerImpl, TM4JRatingManagerImpl

public interface RatingManager

extends ConsensusFoundationModule

The RatingManager manages (stores) the ratings for all rateable elements of the ontology. It must ensure that each rating can only be assigned to at most one rateable element and that each rateable element has not more than one rating per user.

The RatingManager can only manage ratings for concepts and users, although there are other rateable interfaces (see OntologyManager.checkInternalRateable()) - this is why there are several explicit methods for the managed types instead of one polymorphic method with a Rateable parameter.

The RatingManager implementation can be configured with the key cf.ratingmanager in the ConsensusFoundation.properties configuration file. It's an optional component.

The implementation is loaded by the ConsensusFoundation constructor. For successful instantiation, the RatingManager implementation must provide a default constructor without arguments.

Version:

2006-06-14

Author:

Thomas Much

See Also:

ConsensusFoundation, Rateable, OntologyManager.checkInternalRateable(Rateable)

Method Summary

void	addRating(Association rated, Rating rating) Adds the given rating to the given association.
void	addRating(Attribute rated, Rating rating) Adds the given rating to the given attribute.
void	addRating(Topic rated, Rating rating) Adds the given rating to the given topic.
void	addRating(User rated, Rating rating) Adds the given rating to the given user.
void	addRatingListener(RatingListener listener) Registers a new RatingListener.
boolean	changesAllowed() With this method the RatingManager signals if ratings, once added, can be changed afterwards.
Rating	createRating(User creator, double value) Creates a new rating with the given user as the creator ("owner" of the rating).
void	deleteRatings(Association association) If an association is deleted permanently from the ontology, this method can be used to remove the ratings that were added to the association, too (including historical values).
void	deleteRatings(Attribute attribute) If an attribute is deleted permanently from the ontology, this method can be used to remove the ratings that were added to the attribute, too (including historical values).
void	deleteRatings(Topic topic) If a topic is deleted permanently from the ontology, this method can be used to remove the ratings that were added to the topic, too (including historical values).
void	deleteRatings(User user) If a user is deleted permanently from the ontology and user database, this method can be used to remove the ratings that were added to the user, too (including historical values).
double	getAverageRatingValue(Association association) Returns the average (arithmetic mean) of all ratings for the given association.
double	getAverageRatingValue(Attribute attribute) Returns the average (arithmetic mean) of all ratings for the given attribute.
double	getAverageRatingValue(Topic topic) Returns the average (arithmetic mean) of all ratings for the given topic.
double	getAverageRatingValue(User user) Returns the average (arithmetic mean) of all ratings that other users have added to the given user.
Rating	getRating(Association association, User rater) Returns the rating object that the given user has added to the given association (or null if the user hasn't rated the association yet).
Rating	getRating(Attribute attribute, User rater) Returns the rating object that the given user has added to the given attribute (or null if the user hasn't rated the attribute yet).
Rating	getRating(Topic topic, User rater) Returns the rating object that the given user has added to the given topic (or null if the user hasn't rated the topic yet).
Rating	getRating(User user, User rater) Returns the rating object that the given user (parameter "rater") has added to another user (parameter "user") - or null if the user hasn't rated the other user yet.
Collection	getRatings(Association association) Returns a collection of all Rating objects that have been added to the given association.
Collection	getRatings(Attribute attribute) Returns a collection of all Rating objects that have been added to the given attribute.
Collection	getRatings(Topic topic) Returns a collection of all Rating objects that have been added to the given topic.
Collection	getRatings(User user) Returns a collection of all Rating objects that have been added by other users to the given user.
int	getRatingsCount(Association association) Returns the number of ratings that have been added to the given association.
int	getRatingsCount(Attribute attribute) Returns the number of ratings that have been added to the given attribute.
int	getRatingsCount(Topic topic) Returns the number of ratings that have been added to the given topic.
int	getRatingsCount(User user) Returns the number of ratings that have been added by other users to the given user.
double	getUsersAverageOwnRatingsValue(User user) Returns the average (arithmetic mean) of all ratings that the given user has added to other rateable elements.
Collection	getUsersOwnRatings(User user) Returns a collection of all Rating objects that the given user has added to other rateable elements.
int	getUsersOwnRatingsCount(User user) Returns the number of ratings that the given user has added to other rateable elements.
void	init(Properties config, LoggingManager logging, UserManager users, OntologyManager ontology) This method is called by the ConsensusFoundation constructor to initialize the RatingManager.
String	ratingValueToString(double value) As applications will have to store rating values as strings (e.g. in the presentation layer), this method converts a rating value into a string.
void	removeRating(User remover, Rating rating) Removes a rating and its history if it is assigned to a rateable element (otherwise this call is ignored).
void	removeRatingListener(RatingListener listener) Removes a RatingListener, if it is registered with the RatingManager (otherwise this call is ignored).
double	stringToRatingValue(String str) Converts a string returned by ratingValueToString() back into a rating value.

Methods inherited from interface de.uka.ipd.consensus.foundation.ConsensusFoundationModule

getConsensusFoundationManager, getVersion, initCompleted, shutdown

Method Detail

init

public void init(Properties config,
                 LoggingManager logging,
                 UserManager users,
                 OntologyManager ontology)
          throws Exception

This method is called by the ConsensusFoundation constructor to initialize the RatingManager.

Parameters:

config - all entries from ConsensusFoundation.properties

logging - the successfully initialized LoggingManager instance

users - the the successfully initialized UserManager instance

ontology - the the successfully initialized OntologyManager instance

Throws:

Exception - if any error occurs (startup of the application is aborted in this case)

See Also:

ConsensusFoundation.ConsensusFoundation()

createRating

public Rating createRating(User creator,
                           double value)
                    throws RatingManagerException,
                           DynamicRightsManagerException

Creates a new rating with the given user as the creator ("owner" of the rating). The rating is not assigned to any rateable element yet, this is done using the various addRating() methods or - better - the Rateable interface.

Parameters:

creator - the user who wants to create the rating

value - the value for the newly created rating (-1..1, including both values)

Returns:

the newly created rating

Throws:

RatingManagerException - if the rating could not be created

DynamicRightsManagerException - if the user is not allowed to create ratings

See Also:

Rateable.addRating(User, double), DynamicRightsManager.mayCreateRating(User)

addRating

public void addRating(Topic rated,
                      Rating rating)
               throws RatingManagerException,
                      DynamicRightsManagerException

Adds the given rating to the given topic.

The implementation must ensure that each rating can be added to one rateable element only, that each user can rate each topic only once and that historical ratings cannot be added at all.

Parameters:

rated - the topic to which the rating will be added

rating - the rating to be added

Throws:

RatingManagerException - if the rating cannot be added to the given topic

DynamicRightsManagerException - if the user is not allowed to add the rating

See Also:

Rating.isHistorical(), DynamicRightsManager.mayAddRating(Rating, Rateable), Rateable.addRating(User, double)

addRating

public void addRating(Attribute rated,
                      Rating rating)
               throws RatingManagerException,
                      DynamicRightsManagerException

Adds the given rating to the given attribute.

The implementation must ensure that each rating can be added to one rateable element only, that each user can rate each attribute only once and that historical ratings cannot be added at all.

Parameters:

rated - the attribute to which the rating will be added

rating - the rating to be added

Throws:

RatingManagerException - if the rating cannot be added to the given attribute

DynamicRightsManagerException - if the user is not allowed to add the rating

See Also:

Rating.isHistorical(), DynamicRightsManager.mayAddRating(Rating, Rateable), Rateable.addRating(User, double)

addRating

public void addRating(Association rated,
                      Rating rating)
               throws RatingManagerException,
                      DynamicRightsManagerException

Adds the given rating to the given association.

The implementation must ensure that each rating can be added to one rateable element only, that each user can rate each association only once and that historical ratings cannot be added at all.

Parameters:

rated - the association to which the rating will be added

rating - the rating to be added

Throws:

RatingManagerException - if the rating cannot be added to the given association

DynamicRightsManagerException - if the user is not allowed to add the rating

See Also:

Rating.isHistorical(), DynamicRightsManager.mayAddRating(Rating, Rateable), Rateable.addRating(User, double)

addRating

public void addRating(User rated,
                      Rating rating)
               throws RatingManagerException,
                      DynamicRightsManagerException

Adds the given rating to the given user.

The implementation must ensure that each rating can be added to one rateable element only, that each user can rate each other user only once and that historical ratings cannot be added at all.

Parameters:

rated - the user to which the rating will be added

rating - the rating to be added

Throws:

RatingManagerException - if the rating cannot be added to the given user

DynamicRightsManagerException - if the user (who created the rating) is not allowed to add the rating to the given user

See Also:

Rating.isHistorical(), DynamicRightsManager.mayAddRating(Rating, Rateable), Rateable.addRating(User, double)

removeRating

public void removeRating(User remover,
                         Rating rating)
                  throws RatingManagerException,
                         DynamicRightsManagerException

Removes a rating and its history if it is assigned to a rateable element (otherwise this call is ignored).

Parameters:

remover - the user who wants to remove the rating

rating - the rating to be removed

Throws:

RatingManagerException - if the rating could not be removed

DynamicRightsManagerException - if the user is not allowed to remove the rating

See Also:

Rating.getRateable(), DynamicRightsManager.mayRemoveRating(User, Rating)

getRatings

public Collection getRatings(Topic topic)

Returns a collection of all Rating objects that have been added to the given topic.

Only current ratings are taken into account, not historical ones.

Parameters:

topic - the topic for which the ratings are returned

Returns:

a possibly empty collection, never null

See Also:

Rating, Rateable.getRatings()

getRatings

public Collection getRatings(Attribute attribute)

Returns a collection of all Rating objects that have been added to the given attribute.

Only current ratings are taken into account, not historical ones.

Parameters:

attribute - the attribute for which the ratings are returned

Returns:

a possibly empty collection, never null

See Also:

Rating, Rateable.getRatings()

getRatings

public Collection getRatings(Association association)

Returns a collection of all Rating objects that have been added to the given association.

Only current ratings are taken into account, not historical ones.

Parameters:

association - the association for which the ratings are returned

Returns:

a possibly empty collection, never null

See Also:

Rating, Rateable.getRatings()

getRatings

public Collection getRatings(User user)

Returns a collection of all Rating objects that have been added by other users to the given user.

Only current ratings are taken into account, not historical ones.

Parameters:

user - the user for whom the ratings are returned

Returns:

a possibly empty collection, never null

See Also:

Rating, Rateable.getRatings()

getRatingsCount

public int getRatingsCount(Topic topic)

Returns the number of ratings that have been added to the given topic.

Only current ratings are taken into account, not historical ones.

Parameters:

topic - the topic for which the number of ratings shall be returned

Returns:

the number of ratings for the given topic

See Also:

Rateable.getRatingsCount()

getRatingsCount

public int getRatingsCount(Attribute attribute)

Returns the number of ratings that have been added to the given attribute.

Only current ratings are taken into account, not historical ones.

Parameters:

attribute - the attribute for which the number of ratings shall be returned

Returns:

the number of ratings for the given attribute

See Also:

Rateable.getRatingsCount()

getRatingsCount

public int getRatingsCount(Association association)

Returns the number of ratings that have been added to the given association.

Only current ratings are taken into account, not historical ones.

Parameters:

association - the association for which the number of ratings shall be returned

Returns:

the number of ratings for the given association

See Also:

Rateable.getRatingsCount()

getRatingsCount

public int getRatingsCount(User user)

Returns the number of ratings that have been added by other users to the given user.

Only current ratings are taken into account, not historical ones.

Parameters:

user - the user for whom the number of ratings shall be returned

Returns:

the number of other user's ratings for the given user

See Also:

Rateable.getRatingsCount()

getAverageRatingValue

public double getAverageRatingValue(Topic topic)

Returns the average (arithmetic mean) of all ratings for the given topic.

Only current ratings are taken into account, not historical ones.

Parameters:

topic - the topic for which the average rating value shall be computed

Returns:

the arithmetic mean of all ratings or Rating.NEUTRAL if the topic isn't rated yet

See Also:

Rating.NEUTRAL, Rateable.getAverageRatingValue()

getAverageRatingValue

public double getAverageRatingValue(Attribute attribute)

Returns the average (arithmetic mean) of all ratings for the given attribute.

Only current ratings are taken into account, not historical ones.

Parameters:

attribute - the attribute for which the average rating value shall be computed

Returns:

the arithmetic mean of all ratings or Rating.NEUTRAL if the attribute isn't rated yet

See Also:

Rating.NEUTRAL, Rateable.getAverageRatingValue()

getAverageRatingValue

public double getAverageRatingValue(Association association)

Returns the average (arithmetic mean) of all ratings for the given association.

Only current ratings are taken into account, not historical ones.

Parameters:

association - the association for which the average rating value shall be computed

Returns:

the arithmetic mean of all ratings or Rating.NEUTRAL if the association isn't rated yet

See Also:

Rating.NEUTRAL, Rateable.getAverageRatingValue()

getAverageRatingValue

public double getAverageRatingValue(User user)

Returns the average (arithmetic mean) of all ratings that other users have added to the given user.

Only current ratings are taken into account, not historical ones.

Parameters:

user - the user for whom the average rating value shall be computed

Returns:

the arithmetic mean of all ratings or Rating.NEUTRAL if the user isn't rated yet

See Also:

Rating.NEUTRAL, Rateable.getAverageRatingValue()

getRating

public Rating getRating(Topic topic,
                        User rater)

Returns the rating object that the given user has added to the given topic (or null if the user hasn't rated the topic yet).

Parameters:

topic - the topic from which the rating is returned

rater - the user who added the rating

Returns:

the Rating object or null

See Also:

Rateable.getRating(User)

getRating

public Rating getRating(Attribute attribute,
                        User rater)

Returns the rating object that the given user has added to the given attribute (or null if the user hasn't rated the attribute yet).

Parameters:

attribute - the attribute from which the rating is returned

rater - the user who added the rating

Returns:

the Rating object or null

See Also:

Rateable.getRating(User)

getRating

public Rating getRating(Association association,
                        User rater)

Returns the rating object that the given user has added to the given association (or null if the user hasn't rated the association yet).

Parameters:

association - the association from which the rating is returned

rater - the user who added the rating

Returns:

the Rating object or null

See Also:

Rateable.getRating(User)

getRating

public Rating getRating(User user,
                        User rater)

Returns the rating object that the given user (parameter "rater") has added to another user (parameter "user") - or null if the user hasn't rated the other user yet.

Parameters:

user - the user from which the rating is returned

rater - the user who added the rating

Returns:

the Rating object or null

See Also:

Rateable.getRating(User)

getUsersOwnRatings

public Collection getUsersOwnRatings(User user)

Returns a collection of all Rating objects that the given user has added to other rateable elements.

Only current ratings are taken into account, not historical ones.

Parameters:

user - the user from whom the ratings are returned

Returns:

a possibly empty collection, never null

See Also:

Rating, User.getOwnRatings()

getUsersOwnRatingsCount

public int getUsersOwnRatingsCount(User user)

Returns the number of ratings that the given user has added to other rateable elements.

Only current ratings are taken into account, not historical ones.

Parameters:

user - the user from whom the number of ratings shall be returned

Returns:

the number of ratings the given user has added to other elements

See Also:

User.getOwnRatingsCount()

getUsersAverageOwnRatingsValue

public double getUsersAverageOwnRatingsValue(User user)

Returns the average (arithmetic mean) of all ratings that the given user has added to other rateable elements.

Only current ratings are taken into account, not historical ones.

Parameters:

user - the user from whose ratings the average rating value shall be computed

Returns:

the arithmetic mean of all ratings or Rating.NEUTRAL if the user hasn't rated other elements yet

See Also:

Rating.NEUTRAL, User.getAverageOwnRatingsValue()

deleteRatings

public void deleteRatings(Topic topic)
                   throws RatingManagerException

If a topic is deleted permanently from the ontology, this method can be used to remove the ratings that were added to the topic, too (including historical values).

This method will be used by the EvolutionManager.

Parameters:

topic - the topic object for which the corresponding ratings shall be deleted

Throws:

RatingManagerException - if the ratings could not be deleted

See Also:

EvolutionManager.deleteTopic(User, Topic), EvolutionManager.deleteTopicAndSubtopics(User, Topic)

deleteRatings

public void deleteRatings(Attribute attribute)
                   throws RatingManagerException

If an attribute is deleted permanently from the ontology, this method can be used to remove the ratings that were added to the attribute, too (including historical values).

This method will be used by the EvolutionManager.

Parameters:

attribute - the attribute object for which the corresponding ratings shall be deleted

Throws:

RatingManagerException - if the ratings could not be deleted

See Also:

EvolutionManager.deleteAttribute(User, Topic, Attribute)

deleteRatings

public void deleteRatings(Association association)
                   throws RatingManagerException

If an association is deleted permanently from the ontology, this method can be used to remove the ratings that were added to the association, too (including historical values).

This method will be used by the EvolutionManager.

Parameters:

association - the association object for which the corresponding ratings shall be deleted

Throws:

RatingManagerException - if the ratings could not be deleted

See Also:

EvolutionManager.deleteAssociation(User, Association)

deleteRatings

public void deleteRatings(User user)
                   throws RatingManagerException

If a user is deleted permanently from the ontology and user database, this method can be used to remove the ratings that were added to the user, too (including historical values).

This method will be used by the UserManager.

Parameters:

user - the user object for which the corresponding ratings shall be deleted

Throws:

RatingManagerException - if the ratings could not be deleted

See Also:

UserManager.deleteUser(User, String)

ratingValueToString

public String ratingValueToString(double value)

As applications will have to store rating values as strings (e.g. in the presentation layer), this method converts a rating value into a string. If the RatingManager supports discrete values, this method should try to return suitable string for these concrete values instead of simply turning the value number into a string (e.g. "YES", "NO", "NEUTRAL" instead of "1", "-1", "0").

The values are intended to be valid until application shutdown only and may not be compatible between different implementations of the RatingManager interface!

return the given rating value converted to a suitable string

See Also:

Rating.getValue(), stringToRatingValue(String)

stringToRatingValue

public double stringToRatingValue(String str)

Converts a string returned by ratingValueToString() back into a rating value.

If an unknown string is given, Rating.NEUTRAL should be returned.

Parameters:

str - the string to be converted

Returns:

the converted rating value

See Also:

Rating.setValue(double), Rating.NEUTRAL, ratingValueToString(double)

changesAllowed

public boolean changesAllowed()

With this method the RatingManager signals if ratings, once added, can be changed afterwards.

Returns:

true if existing ratings can be changed, false otherwise

addRatingListener

public void addRatingListener(RatingListener listener)

Registers a new RatingListener.

Parameters:

listener - the RatingListener to be added

removeRatingListener

public void removeRatingListener(RatingListener listener)

Removes a RatingListener, if it is registered with the RatingManager (otherwise this call is ignored).

Parameters:

listener - the RatingListener to be removed