Class | Line # | Actions | |||||
---|---|---|---|---|---|---|---|
AnnotationService | 40 | 0 | - | 0 | 0 |
1 | /* | |
2 | * See the NOTICE file distributed with this work for additional | |
3 | * information regarding copyright ownership. | |
4 | * | |
5 | * This is free software; you can redistribute it and/or modify it | |
6 | * under the terms of the GNU Lesser General Public License as | |
7 | * published by the Free Software Foundation; either version 2.1 of | |
8 | * the License, or (at your option) any later version. | |
9 | * | |
10 | * This software is distributed in the hope that it will be useful, | |
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
13 | * Lesser General Public License for more details. | |
14 | * | |
15 | * You should have received a copy of the GNU Lesser General Public | |
16 | * License along with this software; if not, write to the Free | |
17 | * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA | |
18 | * 02110-1301 USA, or see the FSF site: http://www.fsf.org. | |
19 | */ | |
20 | package org.xwiki.annotation; | |
21 | ||
22 | import java.util.Collection; | |
23 | import java.util.Map; | |
24 | ||
25 | import org.xwiki.component.annotation.Role; | |
26 | ||
27 | /** | |
28 | * Component responsible for providing annotations related services: the management of annotations (retrieving, adding, | |
29 | * removing, updating) and rendering them on their respective targets. <br> | |
30 | * This service does not parse or interpret the references of targets its operating with, caller is responsible to be | |
31 | * consistent in calls and use references which are interpreted by the used implementations for | |
32 | * {@link org.xwiki.annotation.io.IOService and org.xwiki.annotation.io.IOTargetService}. <br> | |
33 | * | |
34 | * @version $Id: 00b384fc800c625e306a9387e46d8451cf8f15fc $ | |
35 | * @see org.xwiki.annotation.io.IOTargetService | |
36 | * @see org.xwiki.annotation.io.IOTargetService | |
37 | * @since 2.3M1 | |
38 | */ | |
39 | @Role | |
40 | public interface AnnotationService | |
41 | { | |
42 | /** | |
43 | * Returns the XHTML of the requested source, along with annotations inserted as {@code span} elements inside it. | |
44 | * It's a particular case of {@link #getAnnotatedRenderedContent(String, String, String, Collection)} for | |
45 | * unspecified input syntax, {@code xhtml/1.0} output syntax and the list of annotations returned by | |
46 | * {@link #getValidAnnotations(String)} for this source reference. | |
47 | * | |
48 | * @param sourceReference reference to the source to be rendered in XHTML with annotations | |
49 | * @return rendered and annotated document | |
50 | * @throws AnnotationServiceException if anything goes wrong retrieving or rendering the requested source | |
51 | * @see #getAnnotatedRenderedContent(String, String, String, Collection) | |
52 | */ | |
53 | String getAnnotatedHTML(String sourceReference) throws AnnotationServiceException; | |
54 | ||
55 | /** | |
56 | * Returns result obtained by rendering with annotations markers the source referenced by the | |
57 | * {@code sourceReference} parsed in {@code sourceSyntax}. The list of annotations to be added markers for is passed | |
58 | * in the {@code annotations} parameter. Note that no test is done on the actual target of the annotations in the | |
59 | * passed list, they will all be rendered, as long as their selected text and context can be identified in the | |
60 | * content. | |
61 | * | |
62 | * @param sourceReference the reference to the source to be rendered in XHTML with annotations | |
63 | * @param sourceSyntax the syntax to parse the source in. If this parameter is null, the default source syntax will | |
64 | * be used, as returned by the target IO service. | |
65 | * @param outputSyntax the syntax to render in (e.g. "xhtml/1.0") | |
66 | * @param annotations the annotations to render on the content referred by the {@code sourceReference}. Can be the | |
67 | * whole set of annotations on that source or a subset, filtered by various criteria | |
68 | * @return the annotated rendered source | |
69 | * @throws AnnotationServiceException if anything goes wrong retrieving or rendering the requested source | |
70 | */ | |
71 | String getAnnotatedRenderedContent(String sourceReference, String sourceSyntax, String outputSyntax, | |
72 | Collection<Annotation> annotations) throws AnnotationServiceException; | |
73 | ||
74 | /** | |
75 | * Adds an the specified annotation for the specified target. | |
76 | * | |
77 | * @param target serialized reference of the target of the annotation | |
78 | * @param selection HTML selection concerned by annotations | |
79 | * @param selectionContext HTML selection context | |
80 | * @param offset offset of the selection in context | |
81 | * @param author the author of the annotation | |
82 | * @param metadata annotation metadata, as key, value pairs | |
83 | * @throws AnnotationServiceException if selection resolution fail or if an XWikiException occurred | |
84 | */ | |
85 | void addAnnotation(String target, String selection, String selectionContext, int offset, String author, | |
86 | Map<String, Object> metadata) throws AnnotationServiceException; | |
87 | ||
88 | /** | |
89 | * Remove an annotation given by its identifier, which should be unique among all annotations on the same target. | |
90 | * | |
91 | * @param target the string serialized reference to the content on which the annotation is added | |
92 | * @param annotationID annotation identifier | |
93 | * @throws AnnotationServiceException if anything goes wrong accessing the annotations store | |
94 | */ | |
95 | void removeAnnotation(String target, String annotationID) throws AnnotationServiceException; | |
96 | ||
97 | /** | |
98 | * Updates the passed annotation with the new values. Matching of the annotation is done by the annotation id field, | |
99 | * among all annotations on the same target. | |
100 | * | |
101 | * @param target the string serialized reference to the content on which the annotation is added | |
102 | * @param annotation the new description of the annotation to update, with a valid id | |
103 | * @throws AnnotationServiceException if anything goes wrong accessing the annotations store | |
104 | */ | |
105 | void updateAnnotation(String target, Annotation annotation) throws AnnotationServiceException; | |
106 | ||
107 | /** | |
108 | * Returns all the annotations on the passed content. | |
109 | * | |
110 | * @param target the string serialized reference to the content for which to get the annotations | |
111 | * @return all annotations which target the specified content | |
112 | * @throws AnnotationServiceException if anything goes wrong accessing the annotations store | |
113 | */ | |
114 | Collection<Annotation> getAnnotations(String target) throws AnnotationServiceException; | |
115 | ||
116 | /** | |
117 | * Returns the annotation identified by {@code id} on the specified target. | |
118 | * | |
119 | * @param target the serialized reference to the content on which the annotation is added | |
120 | * @param id the identifier of the annotation | |
121 | * @return the annotation identified by {@code id} | |
122 | * @throws AnnotationServiceException if anything goes wrong accessing the annotations store | |
123 | */ | |
124 | Annotation getAnnotation(String target, String id) throws AnnotationServiceException; | |
125 | ||
126 | /** | |
127 | * Shortcut function to get all annotations which are valid on the specified target, regardless of the updates the | |
128 | * document and its annotations suffered from creation ('safe' or 'updated' state). | |
129 | * | |
130 | * @param target the string serialized reference to the content for which to get the annotations | |
131 | * @return all annotations which are valid on the specified content | |
132 | * @throws AnnotationServiceException if anything goes wrong accessing the annotations store | |
133 | * @see org.xwiki.annotation.maintainer.AnnotationState | |
134 | */ | |
135 | Collection<Annotation> getValidAnnotations(String target) throws AnnotationServiceException; | |
136 | } |