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}