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}