001/*
002 * (C) Copyright 2007-2018 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 *     Nuxeo - initial API and implementation
018 *     Nuno Cunha <[email protected]>
019 *
020 * $Id$
021 */
022
023package org.nuxeo.ecm.platform.comment.api;
024
025import java.util.List;
026
027import org.nuxeo.ecm.core.api.CoreSession;
028import org.nuxeo.ecm.core.api.DocumentModel;
029import org.nuxeo.ecm.core.api.PartialList;
030import org.nuxeo.ecm.platform.comment.api.exceptions.CommentNotFoundException;
031import org.nuxeo.ecm.platform.comment.api.exceptions.CommentSecurityException;
032
033/**
034 * @author <a href="mailto:[email protected]">George Lefter</a>
035 */
036public interface CommentManager {
037
038    /**
039     * Features of the implementation of the service.
040     *
041     * @see CommentManager#hasFeature
042     * @since 10.3
043     */
044    enum Feature {
045        /** Comments are linked with the parent id property. */
046        COMMENTS_LINKED_WITH_PROPERTY,
047    }
048
049    /**
050     * Gets comments of a document.
051     *
052     * @param docModel the document model
053     * @return the list of comments
054     */
055    List<DocumentModel> getComments(DocumentModel docModel);
056
057    /**
058     * Gets comments of a document.
059     *
060     * @param session the core session
061     * @param docModel the document model
062     * @return the list of comments
063     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
064     *             document
065     * @since 10.3
066     */
067    List<DocumentModel> getComments(CoreSession session, DocumentModel docModel) throws CommentSecurityException;
068
069    /**
070     * Get comments of a document.
071     *
072     * @param docModel the document model
073     * @param parent the parent document model
074     * @return the list of comments
075     * @deprecated since 10.3, use {@link #getComments(DocumentModel)} instead.
076     */
077    @Deprecated
078    List<DocumentModel> getComments(DocumentModel docModel, DocumentModel parent);
079
080    /**
081     * Creates a comment.
082     *
083     * @param docModel the document to comment
084     * @param comment the comment content
085     * @deprecated CommentManager cannot find the author if invoked remotely so one should use
086     *             {@link #createComment(DocumentModel, String, String)}
087     */
088    @Deprecated
089    DocumentModel createComment(DocumentModel docModel, String comment);
090
091    /**
092     * Creates a comment document model, filling its properties with given info and linking it to given document.
093     *
094     * @param docModel the document to comment
095     * @param comment the comment content
096     * @param author the comment author
097     * @return the comment document model.
098     * @deprecated since 10.3, use {@link #createComment(CoreSession, Comment)} instead.
099     */
100    @Deprecated
101    DocumentModel createComment(DocumentModel docModel, String comment, String author);
102
103    /**
104     * Creates a comment document model, filling its properties with given info and linking it to given document.
105     *
106     * @param docModel the document to comment
107     * @param comment the comment document model
108     * @return the created comment document model.
109     * @throws CommentSecurityException if the current user does not have the right permissions on the document to
110     *             comment.
111     */
112    DocumentModel createComment(DocumentModel docModel, DocumentModel comment) throws CommentSecurityException;
113
114    /**
115     * Creates a comment document model, filling its properties with given info and linking it to given document.
116     *
117     * @param docModel the document to comment
118     * @param parent the comment parent document model
119     * @param child the comment child document model
120     * @return the created comment document model.
121     * @deprecated since 10.3, use {@link #createComment(CoreSession, Comment)} instead.
122     */
123    @Deprecated
124    DocumentModel createComment(DocumentModel docModel, DocumentModel parent, DocumentModel child);
125
126    /**
127     * Deletes a comment.
128     *
129     * @param docModel the comment document model
130     * @param comment the comment
131     * @deprecated since 10.3, use {@link #deleteComment(CoreSession, String)} instead.
132     */
133    @Deprecated
134    void deleteComment(DocumentModel docModel, DocumentModel comment);
135
136    /**
137     * Gets documents in relation with a particular comment.
138     *
139     * @param comment the comment
140     * @return the list of documents
141     * @deprecated since 10.3, only used with deprecated implementation, no replacement.
142     */
143    @Deprecated
144    List<DocumentModel> getDocumentsForComment(DocumentModel comment);
145
146    /**
147     * Gets thread in relation with a given comment (post or comment).
148     *
149     * @param comment the comment
150     * @return the thread
151     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
152     *             document.
153     * @since 5.5
154     */
155    DocumentModel getThreadForComment(DocumentModel comment) throws CommentSecurityException;
156
157    /**
158     * Creates a comment document model. It gives opportunity to save the comments in a specified location.
159     *
160     * @param docModel the document to comment
161     * @param comment the comment content
162     * @param path the location path
163     * @return the comment document model.
164     * @throws CommentSecurityException if the current user does not have the right permissions on the document to
165     *             comment.
166     */
167    DocumentModel createLocatedComment(DocumentModel docModel, DocumentModel comment, String path)
168            throws CommentSecurityException;
169
170    /**
171     * Creates a comment.
172     *
173     * @param session the core session
174     * @return the created comment
175     * @throws CommentNotFoundException if the document to comment, i.e. comment's parent, does not exist.
176     * @throws CommentSecurityException if the current user does not have the right permissions on the document to
177     *             comment.
178     * @since 10.3
179     */
180    Comment createComment(CoreSession session, Comment comment)
181            throws CommentNotFoundException, CommentSecurityException;
182
183    /**
184     * Gets a comment.
185     *
186     * @param session the core session
187     * @param commentId the comment id
188     * @return the comment
189     * @throws CommentNotFoundException if the comment does not exist
190     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
191     *             document.
192     * @since 10.3
193     */
194    Comment getComment(CoreSession session, String commentId) throws CommentNotFoundException, CommentSecurityException;
195
196    /**
197     * Gets all comments for a document.
198     *
199     * @param session the core session
200     * @param documentId the document id
201     * @return the list of comments, ordered ascending by comment's creation date, or an empty list if no comment is
202     *         found.
203     * @since 10.3
204     */
205    List<Comment> getComments(CoreSession session, String documentId);
206
207    /**
208     * Gets all comments for a document.
209     *
210     * @param session the core session
211     * @param documentId the document id
212     * @param sortAscending whether to sort ascending or descending
213     * @return the list of comments, ordered by comment's creation date and according to sortAscending parameter, or an
214     *         empty list if no comment is found.
215     * @since 10.3
216     */
217    List<Comment> getComments(CoreSession session, String documentId, boolean sortAscending);
218
219    /**
220     * Gets all comments for a document.
221     * 
222     * @param session the core session
223     * @param documentId the document id
224     * @param pageSize the page size to query, give null or 0 to disable pagination
225     * @param currentPageIndex the page index to query, give null or 0 to disable pagination
226     * @return the list of comments, ordered ascending by comment's creation date, or an empty list if no comment is
227     *         found.
228     * @since 10.3
229     */
230    PartialList<Comment> getComments(CoreSession session, String documentId, Long pageSize, Long currentPageIndex);
231
232    /**
233     * Gets all comments for a document.
234     *
235     * @param session the core session
236     * @param documentId the document id
237     * @param pageSize the page size to query, give null or 0 to disable pagination
238     * @param currentPageIndex the page index to query, give null or 0 to disable pagination
239     * @param sortAscending whether to sort ascending or descending
240     * @return the list of comments, ordered by comment's creation date and according to sortAscending parameter, or an
241     *         empty list if no comment is found.
242     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
243     *             document.
244     * @since 10.3
245     */
246    PartialList<Comment> getComments(CoreSession session, String documentId, Long pageSize, Long currentPageIndex,
247            boolean sortAscending) throws CommentSecurityException;
248
249    /**
250     * Updates a comment.
251     * 
252     * @param session the core session
253     * @param commentId the comment id
254     * @param comment the updated comment
255     * @return the updated comment
256     * @throws CommentNotFoundException if no comment was found with the given id.
257     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
258     *             document.
259     * @since 10.3
260     */
261    Comment updateComment(CoreSession session, String commentId, Comment comment)
262            throws CommentNotFoundException, CommentSecurityException;
263
264    /**
265     * Deletes a comment.
266     *
267     * @param session the core session
268     * @param commentId the comment id
269     * @throws CommentNotFoundException if no comment was found with the given id.
270     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
271     *             document.
272     * @since 10.3
273     */
274    void deleteComment(CoreSession session, String commentId) throws CommentNotFoundException, CommentSecurityException;
275
276    /**
277     * Gets a comment generated by an external service.
278     *
279     * @param session the core session
280     * @param entityId the external entity id
281     * @return the comment
282     * @throws CommentNotFoundException if no comment was found with the given external entity id.
283     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
284     *             document.
285     * @since 10.3
286     */
287    Comment getExternalComment(CoreSession session, String entityId)
288            throws CommentNotFoundException, CommentSecurityException;
289
290    /**
291     * Updates an external comment.
292     *
293     * @param session the core session
294     * @param entityId the external entity id
295     * @param comment the comment containing the modifications
296     * @return the updated comment
297     * @throws CommentNotFoundException if no comment was found with the given external entity id.
298     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
299     *             document.
300     * @since 10.3
301     */
302    Comment updateExternalComment(CoreSession session, String entityId, Comment comment)
303            throws CommentNotFoundException, CommentSecurityException;
304
305    /**
306     * Deletes an external comment.
307     *
308     * @param session the core session
309     * @param entityId the external entity id
310     * @throws CommentNotFoundException if no comment was found with the given external entity id.
311     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
312     *             document.
313     * @since 10.3
314     */
315    void deleteExternalComment(CoreSession session, String entityId)
316            throws CommentNotFoundException, CommentSecurityException;
317
318    /**
319     * Checks if a feature is available.
320     *
321     * @since 10.3
322     */
323    boolean hasFeature(Feature feature);
324
325}