001/*
002 * (C) Copyright 2012 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Thomas Roger
018 */
019package org.nuxeo.ecm.rating.api;
020
021import org.nuxeo.ecm.activity.ActivitiesList;
022
023/**
024 * Service handling rating on activity objects.
025 * <p>
026 * The same activity object can handle multiple ratings by using different {@code aspect}s.
027 *
028 * @author <a href="mailto:troger@nuxeo.com">Thomas Roger</a>
029 * @since 5.6
030 */
031public interface RatingService {
032
033    /**
034     * Rates the {@code activityObject} by the {@code username}.
035     *
036     * @param rating the rating
037     * @param aspect the rating aspect
038     */
039    void rate(String username, int rating, String activityObject, String aspect);
040
041    /**
042     * Cancels a rate by the {@code username}.
043     *
044     * @param activityObject the activity object on which cancelling the rate
045     * @param aspect the rating aspect
046     */
047    void cancelRate(String username, String activityObject, String aspect);
048
049    /**
050     * Cancels all rates.
051     *
052     * @param activityObject the activity object on which cancelling the rate
053     * @param aspect the rating aspect may be null.
054     */
055    void cancelRates(String activityObject, String aspect);
056
057    /**
058     * Returns {@code true} if the {@code username} already rated the {@code activityObject} on the given {@code aspect}
059     * , {@code false} otherwise.
060     */
061    boolean hasUserRated(String username, String activityObject, String aspect);
062
063    /**
064     * Returns the rates count for the {@code activityObject} on the given {@code aspect}.
065     */
066    long getRatesCount(String activityObject, String aspect);
067
068    /**
069     * Returns the rates count for the {@code activityObject} on the given {@code aspect} where the rating is equals to
070     * {@code rating}.
071     */
072    long getRatesCount(String activityObject, int rating, String aspect);
073
074    /**
075     * Returns the rates count by {@code username} for the {@code activityObject} on the given {@code aspect}.
076     */
077    long getRatesCountForUser(String username, String activityObject, String aspect);
078
079    /**
080     * Returns the rates count by {@code username} for the {@code activityObject} on the given {@code aspect} where the
081     * rating is equals to {@code rating}.
082     */
083    long getRatesCountForUser(String username, String activityObject, int rating, String aspect);
084
085    /**
086     * Returns the average rating for the {@code activityObject} on the given {@code aspect}.
087     */
088    double getAverageRating(String activityObject, String aspect);
089
090    /**
091     * Returns the average rating by {@code username} for the {@code activityObject} on the given {@code aspect}.
092     */
093    double getAverageRatingForUser(String username, String activityObject, String aspect);
094
095    /**
096     * Returns the list of their rated children {@code activityObject} on the given {@code aspect} with {@code rating}.
097     *
098     * @return a List of activityObject
099     */
100    ActivitiesList getRatedChildren(String activityObject, int rating, String aspect);
101
102    /**
103     * Get the latest docs activities rated by a specific user
104     *
105     * @param username the desired user
106     * @param limit
107     * @return a List of activityObject
108     */
109    ActivitiesList getLastestRatedDocByUser(String username, String aspect, int limit);
110}