001/*
002 * (C) Copyright 2007-2020 Nuxeo (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 <ncunha@nuxeo.com>
019 *     Kevin Leturc <kleturc@nuxeo.com>
020 */
021
022package org.nuxeo.ecm.platform.comment.api;
023
024import java.util.Collection;
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.DocumentRef;
030import org.nuxeo.ecm.core.api.PartialList;
031import org.nuxeo.ecm.platform.comment.api.exceptions.CommentNotFoundException;
032import org.nuxeo.ecm.platform.comment.api.exceptions.CommentSecurityException;
033
034/**
035 * Service to deal with {@link Comment}.
036 * <p>
037 * We call comment the document model representing a comment.
038 * <p>
039 * We call parent/commented document the document model being commented (regular document or comment).
040 * <p>
041 * We call top level document the regular document which owns all comments.
042 */
043public interface CommentManager {
044
045    /**
046     * Features of the implementation of the service.
047     *
048     * @see CommentManager#hasFeature
049     * @since 10.3
050     */
051    enum Feature {
052        /** Comments are linked with the parent id property. */
053        COMMENTS_LINKED_WITH_PROPERTY,
054        /** Comments are special children of commented document. */
055        COMMENTS_ARE_SPECIAL_CHILDREN,
056    }
057
058    /**
059     * Gets comments of a document.
060     *
061     * @param docModel the document model
062     * @return the list of comments
063     */
064    List<DocumentModel> getComments(DocumentModel docModel);
065
066    /**
067     * Gets comments of a document.
068     *
069     * @param session the core session
070     * @param docModel the document model
071     * @return the list of comments
072     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
073     *             document
074     * @since 10.3
075     */
076    List<DocumentModel> getComments(CoreSession session, DocumentModel docModel);
077
078    /**
079     * Get comments of a document.
080     *
081     * @param docModel the document model
082     * @param parent the parent document model
083     * @return the list of comments
084     * @deprecated since 10.3, use {@link #getComments(DocumentModel)} instead.
085     */
086    @Deprecated(since = "10.3", forRemoval = true)
087    List<DocumentModel> getComments(DocumentModel docModel, DocumentModel parent);
088
089    /**
090     * Creates a comment.
091     *
092     * @param docModel the document to comment
093     * @param comment the comment content
094     * @deprecated CommentManager cannot find the author if invoked remotely so one should use
095     *             {@link #createComment(DocumentModel, String, String)}
096     */
097    @Deprecated
098    DocumentModel createComment(DocumentModel docModel, String comment);
099
100    /**
101     * Creates a comment document model, filling its properties with given info and linking it to given document.
102     *
103     * @param docModel the document to comment
104     * @param comment the comment content
105     * @param author the comment author
106     * @return the comment document model.
107     * @deprecated since 10.3, use {@link #createComment(CoreSession, Comment)} instead.
108     */
109    @Deprecated(since = "10.3", forRemoval = true)
110    DocumentModel createComment(DocumentModel docModel, String comment, String author);
111
112    /**
113     * Creates a comment document model, filling its properties with given info and linking it to given document.
114     *
115     * @param docModel the document to comment
116     * @param comment the comment document model
117     * @return the created comment document model.
118     * @throws CommentSecurityException if the current user does not have the right permissions on the document to
119     *             comment.
120     */
121    DocumentModel createComment(DocumentModel docModel, DocumentModel comment);
122
123    /**
124     * Creates a comment document model, filling its properties with given info and linking it to given document.
125     *
126     * @param docModel the document to comment
127     * @param parent the comment parent document model
128     * @param child the comment child document model
129     * @return the created comment document model.
130     * @deprecated since 10.3, use {@link #createComment(CoreSession, Comment)} instead.
131     */
132    @Deprecated(since = "10.3", forRemoval = true)
133    DocumentModel createComment(DocumentModel docModel, DocumentModel parent, DocumentModel child);
134
135    /**
136     * Deletes a comment.
137     *
138     * @param docModel the comment document model
139     * @param comment the comment
140     * @deprecated since 10.3, use {@link #deleteComment(CoreSession, String)} instead.
141     */
142    @Deprecated(since = "10.3", forRemoval = true)
143    void deleteComment(DocumentModel docModel, DocumentModel comment);
144
145    /**
146     * Gets documents in relation with a particular comment.
147     *
148     * @param comment the comment
149     * @return the list of documents
150     * @deprecated since 10.3, only used with deprecated implementation, no replacement.
151     */
152    @Deprecated(since = "10.3", forRemoval = true)
153    List<DocumentModel> getDocumentsForComment(DocumentModel comment);
154
155    /**
156     * Gets thread in relation with a given comment (post or comment).
157     *
158     * @param comment the comment
159     * @return the thread
160     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
161     *             document.
162     * @since 5.5
163     * @deprecated since 11.1, unused
164     */
165    @Deprecated(since = "11.1")
166    DocumentModel getThreadForComment(DocumentModel comment);
167
168    /**
169     * Creates a comment document model. It gives opportunity to save the comments in a specified location.
170     *
171     * @param docModel the document to comment
172     * @param comment the comment content
173     * @param path the location path
174     * @return the comment document model.
175     * @throws CommentSecurityException if the current user does not have the right permissions on the document to
176     *             comment.
177     */
178    DocumentModel createLocatedComment(DocumentModel docModel, DocumentModel comment, String path);
179
180    /**
181     * Creates a comment.
182     *
183     * @param session the core session
184     * @return the created comment
185     * @throws CommentNotFoundException if the document to comment, i.e. comment's parent, does not exist.
186     * @throws CommentSecurityException if the current user does not have the right permissions on the document to
187     *             comment.
188     * @since 10.3
189     */
190    Comment createComment(CoreSession session, Comment comment);
191
192    /**
193     * Gets a comment.
194     *
195     * @param session the core session
196     * @param commentId the comment id
197     * @return the comment
198     * @throws CommentNotFoundException if the comment does not exist
199     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
200     *             document.
201     * @since 10.3
202     */
203    Comment getComment(CoreSession session, String commentId);
204
205    /**
206     * Gets all comments for a document.
207     *
208     * @param session the core session
209     * @param documentId the document id
210     * @return the list of comments, ordered ascending by comment's creation date, or an empty list if no comment is
211     *         found.
212     * @since 10.3
213     */
214    List<Comment> getComments(CoreSession session, String documentId);
215
216    /**
217     * Gets all comments for a document.
218     *
219     * @param session the core session
220     * @param documentId the document id
221     * @param sortAscending whether to sort ascending or descending
222     * @return the list of comments, ordered by comment's creation date and according to sortAscending parameter, or an
223     *         empty list if no comment is found.
224     * @since 10.3
225     */
226    List<Comment> getComments(CoreSession session, String documentId, boolean sortAscending);
227
228    /**
229     * Gets all comments for a document.
230     *
231     * @param session the core session
232     * @param documentId the document id
233     * @param pageSize the page size to query, give null or 0 to disable pagination
234     * @param currentPageIndex the page index to query, give null or 0 to disable pagination
235     * @return the list of comments, ordered ascending by comment's creation date, or an empty list if no comment is
236     *         found.
237     * @since 10.3
238     */
239    PartialList<Comment> getComments(CoreSession session, String documentId, Long pageSize, Long currentPageIndex);
240
241    /**
242     * Gets all comments for a document.
243     *
244     * @param session the core session
245     * @param documentId the document id
246     * @param pageSize the page size to query, give null or 0 to disable pagination
247     * @param currentPageIndex the page index to query, give null or 0 to disable pagination
248     * @param sortAscending whether to sort ascending or descending
249     * @return the list of comments, ordered by comment's creation date and according to sortAscending parameter, or an
250     *         empty list if no comment is found.
251     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
252     *             document.
253     * @since 10.3
254     */
255    PartialList<Comment> getComments(CoreSession session, String documentId, Long pageSize, Long currentPageIndex,
256            boolean sortAscending);
257
258    /**
259     * Gets all comments for a collection of documents.
260     *
261     * @param session the core session
262     * @param documentIds the document ids
263     * @return the list of comments
264     * @since 11.3
265     */
266    List<Comment> getComments(CoreSession session, Collection<String> documentIds);
267
268    /**
269     * Updates a comment.
270     *
271     * @param session the core session
272     * @param commentId the comment id
273     * @param comment the updated comment
274     * @return the updated comment
275     * @throws CommentNotFoundException if no comment was found with the given id.
276     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
277     *             document.
278     * @since 10.3
279     */
280    Comment updateComment(CoreSession session, String commentId, Comment comment);
281
282    /**
283     * Deletes a comment.
284     *
285     * @param session the core session
286     * @param commentId the comment id
287     * @throws CommentNotFoundException if no comment was found with the given id.
288     * @throws CommentSecurityException if the current user does not have the right permissions on the commented
289     *             document.
290     * @since 10.3
291     */
292    void deleteComment(CoreSession session, String commentId);
293
294    /**
295     * @since 10.3
296     * @deprecated since 11.1, use {@link #getExternalComment(CoreSession, String, String)} instead
297     */
298    @Deprecated(since = "11.1")
299    default Comment getExternalComment(CoreSession session, String entityId) {
300        return getExternalComment(session, null, entityId);
301    }
302
303    /**
304     * Gets an external comment by its {@code entityId} under the document with {@code documentId}.
305     *
306     * @return the comment with given {@code entityId} under the document with given {@code documentId}
307     * @throws CommentNotFoundException if no comment was found with the given external entity id
308     * @throws CommentSecurityException if the current user does have the right permissions on the commented document.
309     * @since 11.1
310     */
311    Comment getExternalComment(CoreSession session, String documentId, String entityId);
312
313    /**
314     * @since 10.3
315     * @deprecated since 11.1, use {@link #updateExternalComment(CoreSession, String, String, Comment)} instead
316     */
317    @Deprecated(since = "11.1")
318    default Comment updateExternalComment(CoreSession session, String entityId, Comment comment) {
319        return updateExternalComment(session, null, entityId, comment);
320    }
321
322    /**
323     * Updates an external comment by its {@code entityId} under the document with {@code documentId}.
324     *
325     * @return the updated comment with given {@code entityId} under the document with given {@code documentId}
326     * @throws CommentNotFoundException if no comment was found with the given external entity id
327     * @throws CommentSecurityException if the current user does have the right permissions on the commented document.
328     * @since 11.1
329     */
330    Comment updateExternalComment(CoreSession session, String documentId, String entityId, Comment comment);
331
332    /**
333     * @since 10.3
334     * @deprecated since 11.1, use {@link #deleteExternalComment(CoreSession, String, String)} instead
335     */
336    @Deprecated(since = "11.1")
337    default void deleteExternalComment(CoreSession session, String entityId) {
338        deleteExternalComment(session, null, entityId);
339    }
340
341    /**
342     * Deletes an external comment by its {code entityId} under the document with {@code documentId}.
343     *
344     * @throws CommentNotFoundException if no comment was found with the given external entity id
345     * @throws CommentSecurityException if the current user does have the right permissions on the commented document.
346     * @since 11.1
347     */
348    void deleteExternalComment(CoreSession session, String documentId, String entityId);
349
350    /**
351     * Checks if a feature is available.
352     *
353     * @since 10.3
354     */
355    boolean hasFeature(Feature feature);
356
357    /**
358     * Gets the top level ancestor document ref for the given document model comment ref. No matter how many levels of
359     * comments there is.
360     * <p>
361     * Given a document fileOne, that we comment with commentOne which we reply on with replyOne
362     * <p>
363     * This method will return:
364     * <ul>
365     * <li>CommentManager#getAncestorRef(session, commentOne) = fileOne</li>
366     * <li>CommentManager#getAncestorRef(session, replyOne) = fileOne</li>
367     * </ul>
368     *
369     * @param session the CoreSession
370     * @param commentRef the comment document model ref
371     * @return the top level ancestor document ref
372     * @since 11.1
373     */
374     DocumentRef getTopLevelDocumentRef(CoreSession session, DocumentRef commentRef);
375
376}