Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD