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 Details

    • AnnotationScriptService

      public AnnotationScriptService()

  • Method Details

    • 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

      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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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: