001/*
002 * (C) Copyright 2006-2012 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl-2.1.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Thomas Roger <troger@nuxeo.com>
016 */
017
018package org.nuxeo.ecm.rating.api;
019
020import java.util.Date;
021
022import org.nuxeo.ecm.activity.ActivitiesList;
023import org.nuxeo.ecm.core.api.CoreSession;
024import org.nuxeo.ecm.core.api.DocumentModel;
025
026/**
027 * Service handling likes / dislikes on documents, or any other activity object.
028 * 
029 * @author <a href="mailto:troger@nuxeo.com">Thomas Roger</a>
030 * @since 5.6
031 */
032public interface LikeService {
033
034    /**
035     * Like the given {@code activityObject} by the {@code username}.
036     */
037    void like(String username, String activityObject);
038
039    /**
040     * Convenient method to like a {@link DocumentModel}.
041     * 
042     * @see LikeService#like(String, String)
043     */
044    void like(String username, DocumentModel doc);
045
046    /**
047     * Returns {@code true} if the given {@code username} already liked the {@code activityObject}, {@code false}
048     * otherwise.
049     */
050    boolean hasUserLiked(String username, String activityObject);
051
052    /**
053     * Returns {@code true} if the given {@code username} already liked the {@code doc}, {@code false} otherwise.
054     */
055    boolean hasUserLiked(String username, DocumentModel doc);
056
057    /**
058     * Returns the likes count for the given {@code activityObject}.
059     */
060    long getLikesCount(String activityObject);
061
062    /**
063     * Convenient method to returns the likes count for a {@link DocumentModel}.
064     * 
065     * @see LikeService#getLikesCount(String)
066     */
067    long getLikesCount(DocumentModel doc);
068
069    /**
070     * Dislike the given {@code activityObject} by the {@code username}.
071     */
072    void dislike(String username, String activityObject);
073
074    /**
075     * Convenient method to dislike a {@see DocumentModel}.
076     * 
077     * @see LikeService#dislike(String, String)
078     */
079    void dislike(String username, DocumentModel doc);
080
081    /**
082     * Returns {@code true} if the given {@code username} already disliked the {@code activityObject}, {@code false}
083     * otherwise.
084     */
085    boolean hasUserDisliked(String username, String activityObject);
086
087    /**
088     * Returns {@code true} if the given {@code username} already disliked the {@code doc}, {@code false} otherwise.
089     */
090    boolean hasUserDisliked(String username, DocumentModel doc);
091
092    /**
093     * Returns the dislikes count for the given {@code activityObject}.
094     */
095    long getDislikesCount(String activityObject);
096
097    /**
098     * Convenient method to returns the dislikes count for a {@link DocumentModel}.
099     * 
100     * @see LikeService#getDislikesCount(String)
101     */
102    long getDislikesCount(DocumentModel doc);
103
104    /**
105     * Cancel a like or dislike for the given {@code username}.
106     * 
107     * @param username the username
108     * @param activityObject the activity object on which to cancel the like or dislike.
109     */
110    void cancel(String username, String activityObject);
111
112    /**
113     * Convenient method to cancel a like or dislike on a {@see DocumentModel}.
114     * 
115     * @see LikeService#cancel(String, String)
116     */
117    void cancel(String username, DocumentModel doc);
118
119    /**
120     * Returns the {@see LikeStatus} for the {@code activityObject}.
121     */
122    LikeStatus getLikeStatus(String activityObject);
123
124    /**
125     * Convenient method to return the {@see LikeStatus} for a {@see DocumentModel}.
126     * 
127     * @see LikeService#getLikeStatus(String)
128     */
129    LikeStatus getLikeStatus(DocumentModel doc);
130
131    /**
132     * Returns the {@see LikeStatus} for the {@code username} and {@code activityObject}.
133     * <p>
134     * The returned {@see LikeStatus} will have the information about the like / dislike status of the {@code username}.
135     */
136    LikeStatus getLikeStatus(String username, String activityObject);
137
138    /**
139     * Convenient method to return the {@see LikeStatus} for the {@code username} and a {@see DocumentModel}.
140     * 
141     * @see LikeService#getLikeStatus(String, String)
142     */
143    LikeStatus getLikeStatus(String username, DocumentModel doc);
144
145    /**
146     * An actitivitesList containing a documentActivity or a minimessageActivity as target, the likes count as object,
147     * current user as actor and actor's likes in context.
148     * 
149     * @param limit maximum documents returned
150     * @param source the parent document when child will be reached
151     */
152    ActivitiesList getMostLikedActivities(CoreSession session, int limit, DocumentModel source);
153
154    /**
155     * An actitivitesList containing a documentActivity or a minimessageActivity as target, the likes count as object,
156     * current user as actor and actor's likes in context the result will be between two dates
157     * 
158     * @param limit maximum documents returned
159     * @param source the parent document when child will be reached
160     */
161    ActivitiesList getMostLikedActivities(CoreSession session, int limit, DocumentModel source, Date fromDt, Date toDt);
162}