Package org.xwiki.annotation

Interface AnnotationService

@Role
public interface AnnotationService

Component responsible for providing annotations related services: the management of annotations (retrieving, adding, removing, updating) and rendering them on their respective targets.
This service does not parse or interpret the references of targets its operating with, caller is responsible to be consistent in calls and use references which are interpreted by the used implementations for and org.xwiki.annotation.io.IOTargetService.

Since:

2.3M1

Version:

$Id: d1bd40bb280fa7f0a0e579d503ed8113bdf4b307 $

See Also:

IOTargetService, IOTargetService

Method Summary

Modifier and Type	Method	Description
void	addAnnotation(String target, String selection, String selectionContext, int offset, String author, Map<String,Object> metadata)	Adds an the specified annotation for the specified target.
String	getAnnotatedHTML(String sourceReference)	Returns the XHTML of the requested source, along with annotations inserted as span elements inside it.
String	getAnnotatedRenderedContent(String sourceReference, String sourceSyntax, String outputSyntax, Collection<Annotation> annotations)	Returns result obtained by rendering with annotations markers the source referenced by the sourceReference parsed in sourceSyntax.
Annotation	getAnnotation(String target, String id)	Returns the annotation identified by id on the specified target.
Collection<Annotation>	getAnnotations(String target)	Returns all the annotations on the passed content.
Collection<Annotation>	getValidAnnotations(String target)	Shortcut function to get all annotations which are valid on the specified target, regardless of the updates the document and its annotations suffered from creation ('safe' or 'updated' state).
void	removeAnnotation(String target, String annotationID)	Remove an annotation given by its identifier, which should be unique among all annotations on the same target.
void	updateAnnotation(String target, Annotation annotation)	Updates the passed annotation with the new values.

Method Detail

getAnnotatedHTML

String getAnnotatedHTML(String sourceReference)
                 throws AnnotationServiceException

Returns the XHTML of the requested source, along with annotations inserted as span elements inside it. It's a particular case of getAnnotatedRenderedContent(String, String, String, Collection) for unspecified input syntax, xhtml/1.0 output syntax and the list of annotations returned by getValidAnnotations(String) for this source reference.

Parameters:

sourceReference - reference to the source to be rendered in XHTML with annotations

Returns:

rendered and annotated document

Throws:

AnnotationServiceException - if anything goes wrong retrieving or rendering the requested source

See Also:

getAnnotatedRenderedContent(String, String, String, Collection)

getAnnotatedRenderedContent

String getAnnotatedRenderedContent(String sourceReference,
                                   String sourceSyntax,
                                   String outputSyntax,
                                   Collection<Annotation> annotations)
                            throws AnnotationServiceException

Returns result obtained by rendering with annotations markers the source referenced by the sourceReference parsed in sourceSyntax. The list of annotations to be added markers for is passed in the annotations parameter. Note that no test is done on the actual target of the annotations in the passed list, they will all be rendered, as long as their selected text and context can be identified in the content.

Parameters:

sourceReference - the reference to the source to be rendered in XHTML with annotations

sourceSyntax - the syntax to parse the source in. If this parameter is null, the default source syntax will be used, as returned by the target IO service.

outputSyntax - the syntax to render in (e.g. "xhtml/1.0")

annotations - the annotations to render on the content referred by the sourceReference. Can be the whole set of annotations on that source or a subset, filtered by various criteria

Returns:

the annotated rendered source

Throws:

AnnotationServiceException - if anything goes wrong retrieving or rendering the requested source

addAnnotation

void addAnnotation(String target,
                   String selection,
                   String selectionContext,
                   int offset,
                   String author,
                   Map<String,Object> metadata)
            throws AnnotationServiceException

Adds an the specified annotation for the specified target.

Parameters:

target - serialized reference of the target of the annotation

selection - HTML selection concerned by annotations

selectionContext - HTML selection context

offset - offset of the selection in context

author - the author of the annotation

metadata - annotation metadata, as key, value pairs

Throws:

AnnotationServiceException - if selection resolution fail or if an XWikiException occurred

removeAnnotation

void removeAnnotation(String target,
                      String annotationID)
               throws AnnotationServiceException

Remove an annotation given by its identifier, which should be unique among all annotations on the same target.

Parameters:

target - the string serialized reference to the content on which the annotation is added

annotationID - annotation identifier

Throws:

AnnotationServiceException - if anything goes wrong accessing the annotations store

updateAnnotation

void updateAnnotation(String target,
                      Annotation annotation)
               throws AnnotationServiceException

Updates the passed annotation with the new values. Matching of the annotation is done by the annotation id field, among all annotations on the same target.

Parameters:

target - the string serialized reference to the content on which the annotation is added

annotation - the new description of the annotation to update, with a valid id

Throws:

AnnotationServiceException - if anything goes wrong accessing the annotations store

getAnnotations

Collection<Annotation> getAnnotations(String target)
                               throws AnnotationServiceException

Returns all the annotations on the passed content.

Parameters:

target - the string serialized reference to the content for which to get the annotations

Returns:

all annotations which target the specified content

Throws:

AnnotationServiceException - if anything goes wrong accessing the annotations store

getAnnotation

Annotation getAnnotation(String target,
                         String id)
                  throws AnnotationServiceException

Returns the annotation identified by id on the specified target.

Parameters:

target - the serialized reference to the content on which the annotation is added

id - the identifier of the annotation

Returns:

the annotation identified by id

Throws:

AnnotationServiceException - if anything goes wrong accessing the annotations store

getValidAnnotations

Collection<Annotation> getValidAnnotations(String target)
                                    throws AnnotationServiceException

Shortcut function to get all annotations which are valid on the specified target, regardless of the updates the document and its annotations suffered from creation ('safe' or 'updated' state).

Parameters:

target - the string serialized reference to the content for which to get the annotations

Returns:

all annotations which are valid on the specified content

Throws:

AnnotationServiceException - if anything goes wrong accessing the annotations store

See Also:

AnnotationState