1. Project Clover database Tue Dec 20 2016 21:24:09 CET
  2. Package org.xwiki.annotation

File AnnotationService.java

 

Code metrics

0
0
0
1
136
18
0
-
-
0
-

Classes

Class Line # Actions
AnnotationService 40 0 - 0 0
-1.0 -
 

Contributing tests

No tests hitting this source file were found.

Source view

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    }