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