001/* 002 * (C) Copyright 2018-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 * Funsho David 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.List; 025 026import org.nuxeo.ecm.core.api.CoreSession; 027import org.nuxeo.ecm.platform.comment.api.exceptions.CommentNotFoundException; 028import org.nuxeo.ecm.platform.comment.api.exceptions.CommentSecurityException; 029 030/** 031 * Annotation API to perform CRUD operations on annotations. 032 * 033 * @since 10.1 034 */ 035public interface AnnotationService { 036 037 /** 038 * Creates an annotation on a document. 039 * 040 * @param session the core session 041 * @param annotation the annotation to create 042 * @return the created annotation 043 * @throws CommentSecurityException if the current user does have the right permissions on the document to annotate. 044 */ 045 Annotation createAnnotation(CoreSession session, Annotation annotation) throws CommentSecurityException; 046 047 /** 048 * Gets an annotation. 049 * 050 * @param session the core session 051 * @param annotationId the annotation document model id 052 * @return the annotation, or {@code null} if the annotation with the given id was not found 053 * @throws CommentNotFoundException if no annotation was found with the given id 054 * @throws CommentSecurityException if the current user does have the right permissions on the annotated document. 055 */ 056 Annotation getAnnotation(CoreSession session, String annotationId) 057 throws CommentNotFoundException, CommentSecurityException; 058 059 /** 060 * Gets all annotations for a document. 061 * 062 * @param session the core session 063 * @param documentId the annotated document id 064 * @param xpath the annotated blob xpath in the document 065 * @throws CommentNotFoundException if no annotation was found with the given id 066 * @throws CommentSecurityException if the current user does have the right permissions on the annotated document. 067 * @return the list of annotations, or an empty list if no annotation is found 068 */ 069 List<Annotation> getAnnotations(CoreSession session, String documentId, String xpath) 070 throws CommentNotFoundException, CommentSecurityException; 071 072 /** 073 * Updates an annotation for a document. 074 * 075 * @param session the core session 076 * @param annotationId the annotation document model id 077 * @param annotation the annotation containing the modifications 078 * @throws CommentNotFoundException if no annotation was found with the given id 079 * @throws CommentSecurityException if the current user does have the right permissions on the annotated document. 080 */ 081 void updateAnnotation(CoreSession session, String annotationId, Annotation annotation) 082 throws CommentNotFoundException, CommentSecurityException; 083 084 /** 085 * Deletes an annotation for a document. 086 * 087 * @param session the core session 088 * @param annotationId the annotation document model id 089 * @throws CommentNotFoundException if no annotation was found with the given id 090 * @throws CommentSecurityException if the current user does have the right permissions on the annotated document. 091 */ 092 void deleteAnnotation(CoreSession session, String annotationId) 093 throws CommentNotFoundException, CommentSecurityException; 094 095 /** 096 * @since 10.3 097 * @deprecated since 11.1, use {@link #getExternalAnnotation(CoreSession, String, String)} instead 098 */ 099 @Deprecated(since = "11.1") 100 default Annotation getExternalAnnotation(CoreSession session, String entityId) 101 throws CommentNotFoundException, CommentSecurityException { 102 return getExternalAnnotation(session, null, entityId); 103 } 104 105 /** 106 * Gets an external annotation by its {@code entityId} under the document with {@code documentId}. 107 * 108 * @return the annotation with given {@code entityId} under the document with given {@code documentId} 109 * @throws CommentNotFoundException if no annotation was found with the given external entity id 110 * @throws CommentSecurityException if the current user does have the right permissions on the annotated document. 111 * @since 11.1 112 */ 113 Annotation getExternalAnnotation(CoreSession session, String documentId, String entityId); 114 115 /** 116 * @since 10.3 117 * @deprecated since 11.1, use {@link #updateExternalAnnotation(CoreSession, String, String, Annotation)} instead 118 */ 119 @Deprecated(since = "11.1") 120 default void updateExternalAnnotation(CoreSession session, String entityId, Annotation annotation) 121 throws CommentNotFoundException, CommentSecurityException { 122 updateExternalAnnotation(session, null, entityId, annotation); 123 } 124 125 /** 126 * Updates an external annotation by its {@code entityId} under the document with {@code documentId}. 127 * 128 * @return the updated annotation with given {@code entityId} under the document with given {@code documentId} 129 * @throws CommentNotFoundException if no annotation was found with the given external entity id 130 * @throws CommentSecurityException if the current user does have the right permissions on the annotated document. 131 * @since 11.1 132 */ 133 Annotation updateExternalAnnotation(CoreSession session, String documentId, String entityId, Annotation annotation); 134 135 /** 136 * @since 10.3 137 * @deprecated since 11.1, use {@link #deleteExternalAnnotation(CoreSession, String, String)} instead 138 */ 139 @Deprecated(since = "11.1") 140 default void deleteExternalAnnotation(CoreSession session, String entityId) 141 throws CommentNotFoundException, CommentSecurityException { 142 deleteExternalAnnotation(session, null, entityId); 143 } 144 145 /** 146 * Deletes an external annotation by its {code entityId} under the document with {@code documentId}. 147 * 148 * @throws CommentNotFoundException if no annotation was found with the given external entity id 149 * @throws CommentSecurityException if the current user does have the right permissions on the annotated document. 150 * @since 11.1 151 */ 152 void deleteExternalAnnotation(CoreSession session, String documentId, String entityId); 153 154}