Package org.xwiki.annotation.script

Class AnnotationScriptService

java.lang.Object

org.xwiki.annotation.script.AnnotationScriptService

All Implemented Interfaces:

org.xwiki.script.service.ScriptService

@Component
@Named("annotations")
@Singleton
public class AnnotationScriptService
extends Object
implements org.xwiki.script.service.ScriptService

Wrapper for the annotation service functions to be exposed to scripting contexts.

Since:

3.0RC1

Version:

$Id: e66808fa62973d78591536b58acaba7a243748cb $

Constructor Summary

Constructors

Constructor	Description
AnnotationScriptService()

Method Summary

Modifier and Type	Method	Description
boolean	addAnnotation(String target, String selection, String selectionContext, int offset, String author, Map<String,Object> metadata)	Adds an the specified annotation for the specified target.
boolean	canAddAnnotation(String wiki, String space, String page)	Deprecated. since 7.2M3, use canAddAnnotation(DocumentReference) instead
boolean	canAddAnnotation(DocumentReference reference)	Checks if the current user can add an annotation on the document given by the reference.
boolean	canEditAnnotation(String annotationId, String wiki, String space, String page)	Deprecated. since 7.2M3, use canEditAnnotation(String, DocumentReference) instead
boolean	canEditAnnotation(String annotationId, DocumentReference reference)	Checks if the current user can edit an annotation on the document given by wiki, space and page.
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.
Annotation	getAnnotation(EntityReference reference, 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).
boolean	removeAnnotation(String target, String annotationID)	Remove an annotation given by its identifier, which should be unique among all annotations on the same target.
boolean	updateAnnotation(String target, Annotation annotation)	Updates the passed annotation with the new values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AnnotationScriptService

public AnnotationScriptService()

Method Detail

addAnnotation

public boolean addAnnotation(String target,
                             String selection,
                             String selectionContext,
                             int offset,
                             String author,
                             Map<String,Object> metadata)

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

Returns:

true if the adding succeeds, false if an exception occurs and the exception is saved on the xwiki context

getAnnotatedHTML

public String getAnnotatedHTML(String sourceReference)

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 or null if an exception occurs and the exception is saved on the xwiki context

See Also:

getAnnotatedRenderedContent(String, String, String, Collection), AnnotationService.getAnnotatedHTML(String)

getAnnotatedRenderedContent

public 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. 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, or @code null} if an exception occurs and the exception is saved on the xwiki context

See Also:

AnnotationService.getAnnotatedRenderedContent(String, String, String, Collection)

getAnnotation

public Annotation getAnnotation(String target,
                                String id)

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, or null if an exception occurs and the exception is saved on the xwiki context

See Also:

AnnotationService.getAnnotation(String, String)

getAnnotation

public Annotation getAnnotation(EntityReference reference,
                                String id)

Returns the annotation identified by id on the specified target.

Parameters:

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

id - the identifier of the annotation

Returns:

the annotation identified by id, or null if an exception occurs and the exception is saved on the xwiki context

See Also:

AnnotationService.getAnnotation(String, String)

getAnnotations

public Collection<Annotation> getAnnotations(String target)

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, or null if an exception occurs and the exception is saved on the xwiki context

See Also:

AnnotationService.getAnnotations(String)

getValidAnnotations

public 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).

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, or null if an exception occurs and the exception is saved on the xwiki context

See Also:

AnnotationState, AnnotationService.getValidAnnotations(String)

removeAnnotation

public boolean removeAnnotation(String target,
                                String annotationID)

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

Returns:

true if removing succeeds, false if an exception occurs and the exception is saved on the xwiki context

See Also:

AnnotationService.removeAnnotation(String, String)

updateAnnotation

public boolean updateAnnotation(String target,
                                Annotation annotation)

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

Returns:

true if update succeeds, false if an exception occurs and the exception is saved on the xwiki context

See Also:

AnnotationService.updateAnnotation(String, Annotation)

canEditAnnotation

@Deprecated
public boolean canEditAnnotation(String annotationId,
                                 String wiki,
                                 String space,
                                 String page)

Deprecated.

since 7.2M3, use canEditAnnotation(String, DocumentReference) instead

Checks if the current user can edit an annotation on the document given by wiki, space and page. This function is a helper function, using wiki, space and page instead of the target to avoid target generation in velocity scripting.
TODO: annotations should only operate on targets, and velocity context should only operate with targets so that they can pass a target to this function. This also assumes refactoring of the REST service to always get target references instead of wiki, space and pages in the path.

Parameters:

annotationId - the id of the annotation to edit

wiki - the wiki of the document where the annotation is added

space - the space of the document where the annotation is added

page - the document page

Returns:

true if the current user can edit the annotation identified by the id on the specified document, false otherwise

canEditAnnotation

public boolean canEditAnnotation(String annotationId,
                                 DocumentReference reference)

Checks if the current user can edit an annotation on the document given by wiki, space and page.

Parameters:

annotationId - the id of the annotation to edit

reference - the reference of the document where the annotation is added

Returns:

true if the current user can edit the annotation identified by the id on the specified document, false otherwise

Since:

7.2M3

canAddAnnotation

@Deprecated
public boolean canAddAnnotation(String wiki,
                                String space,
                                String page)

Deprecated.

since 7.2M3, use canAddAnnotation(DocumentReference) instead

Checks if the current user can add an annotation on the document given by the wiki, space and page. This function is a helper function, using wiki, space and page instead of the target to avoid target generation in velocity scripting.

Parameters:

wiki - the wiki of the document where the annotation is added

space - the space of the document where the annotation is added

page - the document page

Returns:

true if the current user can add an annotation on the specified document, false otherwise

See Also:

canEditAnnotation(String, String, String, String)

canAddAnnotation

public boolean canAddAnnotation(DocumentReference reference)

Checks if the current user can add an annotation on the document given by the reference.

Parameters:

reference - the reference of the document where the annotation is added

Returns:

true if the current user can add an annotation on the specified document, false otherwise

Since:

7.2M3

See Also:

canEditAnnotation(String, String, String, String)