001package org.nuxeo.ecm.rating.api;
002
003import org.nuxeo.ecm.activity.ActivitiesList;
004
005/**
006 * Service handling rating on activity objects.
007 * <p>
008 * The same activity object can handle multiple ratings by using different {@code aspect}s.
009 * 
010 * @author <a href="mailto:troger@nuxeo.com">Thomas Roger</a>
011 * @since 5.6
012 */
013public interface RatingService {
014
015    /**
016     * Rates the {@code activityObject} by the {@code username}.
017     * 
018     * @param rating the rating
019     * @param aspect the rating aspect
020     */
021    void rate(String username, int rating, String activityObject, String aspect);
022
023    /**
024     * Cancels a rate by the {@code username}.
025     * 
026     * @param activityObject the activity object on which cancelling the rate
027     * @param aspect the rating aspect
028     */
029    void cancelRate(String username, String activityObject, String aspect);
030
031    /**
032     * Cancels all rates.
033     *
034     * @param activityObject the activity object on which cancelling the rate
035     * @param aspect the rating aspect may be null.
036     */
037    void cancelRates(String activityObject, String aspect);
038
039    /**
040     * Returns {@code true} if the {@code username} already rated the {@code activityObject} on the given {@code aspect}
041     * , {@code false} otherwise.
042     */
043    boolean hasUserRated(String username, String activityObject, String aspect);
044
045    /**
046     * Returns the rates count for the {@code activityObject} on the given {@code aspect}.
047     */
048    long getRatesCount(String activityObject, String aspect);
049
050    /**
051     * Returns the rates count for the {@code activityObject} on the given {@code aspect} where the rating is equals to
052     * {@code rating}.
053     */
054    long getRatesCount(String activityObject, int rating, String aspect);
055
056    /**
057     * Returns the rates count by {@code username} for the {@code activityObject} on the given {@code aspect}.
058     */
059    long getRatesCountForUser(String username, String activityObject, String aspect);
060
061    /**
062     * Returns the rates count by {@code username} for the {@code activityObject} on the given {@code aspect} where the
063     * rating is equals to {@code rating}.
064     */
065    long getRatesCountForUser(String username, String activityObject, int rating, String aspect);
066
067    /**
068     * Returns the average rating for the {@code activityObject} on the given {@code aspect}.
069     */
070    double getAverageRating(String activityObject, String aspect);
071
072    /**
073     * Returns the average rating by {@code username} for the {@code activityObject} on the given {@code aspect}.
074     */
075    double getAverageRatingForUser(String username, String activityObject, String aspect);
076
077    /**
078     * Returns the list of their rated children {@code activityObject} on the given {@code aspect} with {@code rating}.
079     *
080     * @return a List of activityObject
081     */
082    ActivitiesList getRatedChildren(String activityObject, int rating, String aspect);
083
084    /**
085     * Get the latest docs activities rated by a specific user
086     *
087     * @param username the desired user
088     * @param limit
089     * @return a List of activityObject
090     */
091    ActivitiesList getLastestRatedDocByUser(String username, String aspect, int limit);
092}