001/*
002 * (C) Copyright 2006-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 <troger@nuxeo.com>
018 */
019
020package org.nuxeo.ecm.rating.api;
021
022import java.util.Date;
023
024import org.nuxeo.ecm.activity.ActivitiesList;
025import org.nuxeo.ecm.core.api.CoreSession;
026import org.nuxeo.ecm.core.api.DocumentModel;
027
028/**
029 * Service handling likes / dislikes on documents, or any other activity object.
030 * 
031 * @author <a href="mailto:troger@nuxeo.com">Thomas Roger</a>
032 * @since 5.6
033 */
034public interface LikeService {
035
036    /**
037     * Like the given {@code activityObject} by the {@code username}.
038     */
039    void like(String username, String activityObject);
040
041    /**
042     * Convenient method to like a {@link DocumentModel}.
043     * 
044     * @see LikeService#like(String, String)
045     */
046    void like(String username, DocumentModel doc);
047
048    /**
049     * Returns {@code true} if the given {@code username} already liked the {@code activityObject}, {@code false}
050     * otherwise.
051     */
052    boolean hasUserLiked(String username, String activityObject);
053
054    /**
055     * Returns {@code true} if the given {@code username} already liked the {@code doc}, {@code false} otherwise.
056     */
057    boolean hasUserLiked(String username, DocumentModel doc);
058
059    /**
060     * Returns the likes count for the given {@code activityObject}.
061     */
062    long getLikesCount(String activityObject);
063
064    /**
065     * Convenient method to returns the likes count for a {@link DocumentModel}.
066     * 
067     * @see LikeService#getLikesCount(String)
068     */
069    long getLikesCount(DocumentModel doc);
070
071    /**
072     * Dislike the given {@code activityObject} by the {@code username}.
073     */
074    void dislike(String username, String activityObject);
075
076    /**
077     * Convenient method to dislike a {@see DocumentModel}.
078     * 
079     * @see LikeService#dislike(String, String)
080     */
081    void dislike(String username, DocumentModel doc);
082
083    /**
084     * Returns {@code true} if the given {@code username} already disliked the {@code activityObject}, {@code false}
085     * otherwise.
086     */
087    boolean hasUserDisliked(String username, String activityObject);
088
089    /**
090     * Returns {@code true} if the given {@code username} already disliked the {@code doc}, {@code false} otherwise.
091     */
092    boolean hasUserDisliked(String username, DocumentModel doc);
093
094    /**
095     * Returns the dislikes count for the given {@code activityObject}.
096     */
097    long getDislikesCount(String activityObject);
098
099    /**
100     * Convenient method to returns the dislikes count for a {@link DocumentModel}.
101     * 
102     * @see LikeService#getDislikesCount(String)
103     */
104    long getDislikesCount(DocumentModel doc);
105
106    /**
107     * Cancel a like or dislike for the given {@code username}.
108     * 
109     * @param username the username
110     * @param activityObject the activity object on which to cancel the like or dislike.
111     */
112    void cancel(String username, String activityObject);
113
114    /**
115     * Convenient method to cancel a like or dislike on a {@see DocumentModel}.
116     * 
117     * @see LikeService#cancel(String, String)
118     */
119    void cancel(String username, DocumentModel doc);
120
121    /**
122     * Returns the {@see LikeStatus} for the {@code activityObject}.
123     */
124    LikeStatus getLikeStatus(String activityObject);
125
126    /**
127     * Convenient method to return the {@see LikeStatus} for a {@see DocumentModel}.
128     * 
129     * @see LikeService#getLikeStatus(String)
130     */
131    LikeStatus getLikeStatus(DocumentModel doc);
132
133    /**
134     * Returns the {@see LikeStatus} for the {@code username} and {@code activityObject}.
135     * <p>
136     * The returned {@see LikeStatus} will have the information about the like / dislike status of the {@code username}.
137     */
138    LikeStatus getLikeStatus(String username, String activityObject);
139
140    /**
141     * Convenient method to return the {@see LikeStatus} for the {@code username} and a {@see DocumentModel}.
142     * 
143     * @see LikeService#getLikeStatus(String, String)
144     */
145    LikeStatus getLikeStatus(String username, DocumentModel doc);
146
147    /**
148     * An actitivitesList containing a documentActivity or a minimessageActivity as target, the likes count as object,
149     * current user as actor and actor's likes in context.
150     * 
151     * @param limit maximum documents returned
152     * @param source the parent document when child will be reached
153     */
154    ActivitiesList getMostLikedActivities(CoreSession session, int limit, DocumentModel source);
155
156    /**
157     * An actitivitesList containing a documentActivity or a minimessageActivity as target, the likes count as object,
158     * current user as actor and actor's likes in context the result will be between two dates
159     * 
160     * @param limit maximum documents returned
161     * @param source the parent document when child will be reached
162     */
163    ActivitiesList getMostLikedActivities(CoreSession session, int limit, DocumentModel source, Date fromDt, Date toDt);
164}