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 *
019 */
020
021package org.nuxeo.ecm.annotation;
022
023import org.nuxeo.ecm.core.api.CoreSession;
024
025import java.util.List;
026
027/**
028 * Annotation API to perform CRUD operations on annotations.
029 *
030 * @since 10.1
031 */
032public interface AnnotationService {
033
034    /**
035     * Creates an annotation on a document.
036     *
037     * @param session the core session
038     * @param annotation the annotation to create
039     * @return the created annotation
040     */
041    Annotation createAnnotation(CoreSession session, Annotation annotation);
042
043    /**
044     * Gets an annotation.
045     *
046     * @param session the core session
047     * @param annotationId the annotation id
048     * @return the annotation, or {@code null} if the annotation with the given id was not found
049     */
050    Annotation getAnnotation(CoreSession session, String annotationId);
051
052    /**
053     * Gets all annotations for a document.
054     *
055     * @param session the core session
056     * @param documentId the annotated document id
057     * @param xpath the annotated blob xpath in the document
058     * @return the list of annotations, or an empty list if no annotation is found
059     */
060    List<Annotation> getAnnotations(CoreSession session, String documentId, String xpath);
061
062    /**
063     * Updates an annotation for a document.
064     *
065     * @param session the core session
066     * @param annotation the annotation containing the modifications
067     */
068    void updateAnnotation(CoreSession session, Annotation annotation);
069
070    /**
071     * Deletes an annotation for a document.
072     *
073     * @param session the core session
074     * @param annotationId the annotation id
075     * @throws IllegalArgumentException if no annotation was found with the given id
076     */
077    void deleteAnnotation(CoreSession session, String annotationId)
078            throws IllegalArgumentException;
079
080}