public interface

AnnotationProvider

com.pspdfkit.annotations.AnnotationProvider
Known Indirect Subclasses

Class Overview

Handles all annotation related operations on the owning document. Retrieve it with getAnnotationProvider().

Summary

Nested Classes
interface AnnotationProvider.OnAnnotationUpdatedListener Listener for annotation update events inside AnnotationProvider
Fields
public static final EnumSet<AnnotationType> ALL_ANNOTATION_TYPES All annotation types that can displayed in the annotation list.
Public Methods
abstract void addAnnotationToPage(Annotation annotation)
Adds annotation to the owner PDF document.
abstract Completable addAnnotationToPageAsync(Annotation annotation)
Adds annotation to the owner PDF document asynchronously.
abstract void addAppearanceStreamGenerator(AppearanceStreamGenerator appearanceStreamGenerator)

Adds appearance stream generator to the list of global appearance stream generators.

abstract void addAppearanceStreamGenerator(AppearanceStreamGenerator appearanceStreamGenerator, boolean addFirst)

Adds appearance stream generator to the list of global appearance stream generators.

abstract void addOnAnnotationUpdatedListener(AnnotationProvider.OnAnnotationUpdatedListener updatedListener)
Adds an AnnotationProvider.OnAnnotationUpdatedListener for being notified of updates to annotations.
abstract void appendAnnotationState(Annotation annotation, AnnotationStateChange annotationStateChange)
Appends a new annotation state for the given annotation (adds it to the review history).
abstract Completable appendAnnotationStateAsync(Annotation annotation, AnnotationStateChange annotationStateChange)
Appends a new annotation state for the given annotation asynchronously (adds it to the review history).
abstract Annotation createAnnotationFromInstantJson(String annotationJson)
Creates an annotation from the Instant JSON annotation format.
abstract Single<Annotation> createAnnotationFromInstantJsonAsync(String annotationJson)
Creates an annotation from the Instant JSON annotation format asynchronously.
abstract Observable<Annotation> getAllAnnotationsOfType(EnumSet<AnnotationType> types, int startIndex, int pageCount)
Returns all annotations of passed types in the specified page index range.
abstract Observable<Annotation> getAllAnnotationsOfType(EnumSet<AnnotationType> types)
Returns all annotations of passed types in this document.
abstract Annotation getAnnotation(int pageIndex, int objectNumber)
Returns annotation with certain object ID on the page if it exists.
abstract Maybe<Annotation> getAnnotationAsync(int pageIndex, int objectNumber)
Returns annotation with certain object ID on the page if it exists, asynchronously.
abstract List<Annotation> getAnnotationReplies(Annotation annotation)
Get all first-level replies to a particular annotation.
abstract Single<List<Annotation>> getAnnotationRepliesAsync(Annotation annotation)
Get all first-level replies to a particular annotation asynchronously.
abstract List<Annotation> getAnnotations(Collection<Integer> objectNumbers)
Returns annotations with given object numbers.
abstract List<Annotation> getAnnotations(int pageIndex)
Returns a list of annotations on the page.
abstract Observable<List<Annotation>> getAnnotationsAsync(int pageIndex)
Returns list of annotations on the page.
abstract Observable<List<Annotation>> getAnnotationsAsync(Collection<Integer> objectNumbers)
Returns annotations with given object numbers, asynchronously.
abstract List<Annotation> getFlattenedAnnotationReplies(Annotation annotation)
Get all flattened replies (all replies included but no nesting) to a particular annotation.
abstract Single<List<Annotation>> getFlattenedAnnotationRepliesAsync(Annotation annotation)
Get all flattened replies (all replies included but no nesting) to a particular annotation asynchronously.
abstract List<AnnotationStateChange> getReviewHistory(Annotation annotation)
Get the review history of an annotation.
abstract Single<List<AnnotationStateChange>> getReviewHistoryAsync(Annotation annotation)
Get the review history of an annotation asynchronously.
abstract AnnotationReviewSummary getReviewSummary(Annotation annotation, String currentUser)
Get a summary information about the given annotation's review state.
abstract Maybe<AnnotationReviewSummary> getReviewSummaryAsync(Annotation annotation, String currentUser)
Get a summary information about the given annotation's review state asynchronously.
abstract boolean hasUnsavedChanges()
Returns whether there are unsaved changes to annotations in this document.
abstract void removeAnnotationFromPage(Annotation annotation)
Removes annotation from the document.
abstract Completable removeAnnotationFromPageAsync(Annotation annotation)
Removes annotation from this document asynchronously.
abstract void removeAppearanceStreamGenerator(AppearanceStreamGenerator appearanceStreamGenerator)
Remove appearance stream generator that was previously added in addAppearanceStreamGenerator(AppearanceStreamGenerator).
abstract void removeOnAnnotationUpdatedListener(AnnotationProvider.OnAnnotationUpdatedListener updatedListener)

Fields

public static final EnumSet<AnnotationType> ALL_ANNOTATION_TYPES

All annotation types that can displayed in the annotation list.

Public Methods

public abstract void addAnnotationToPage (Annotation annotation)

Adds annotation to the owner PDF document. The annotation will be attached to the page set in its constructor.

Parameters
annotation Annotation to be added to the document.

public abstract Completable addAnnotationToPageAsync (Annotation annotation)

Adds annotation to the owner PDF document asynchronously. The annotation will be attached to the page set in its constructor.

Parameters
annotation Annotation to be added to the document.
Returns
  • Completable which has to be subscribed to for operation to run.

public abstract void addAppearanceStreamGenerator (AppearanceStreamGenerator appearanceStreamGenerator)

Adds appearance stream generator to the list of global appearance stream generators.

Appearance stream generators in this list are queried for all annotations in the document until one of them returns true from shouldUseGeneratorForAnnotation(Annotation). This generator is then used to generate custom appearance stream by calling getDataProviderForAnnotation(Annotation, EnumSet). If no such generator is found in the list, annotation's generator (set via setAppearanceStreamGenerator(AppearanceStreamGenerator) is used. Appearance stream generation fallbacks to default rendering if annotation has no appearance stream generator set.


Note: This does not automatically remove existing appearance streams. The appearance stream only gets generated when the annotation has been modified or when calling generateAppearanceStream() explicitly.

Parameters
appearanceStreamGenerator Appearance stream generator.

public abstract void addAppearanceStreamGenerator (AppearanceStreamGenerator appearanceStreamGenerator, boolean addFirst)

Adds appearance stream generator to the list of global appearance stream generators.

Appearance stream generators in this list are queried in order until one of them returns true from shouldUseGeneratorForAnnotation(Annotation). This generator is then used to generate custom appearance stream for the annotation by calling getDataProviderForAnnotation(Annotation, EnumSet). If no such generator is found in the list, annotation's generator (set via setAppearanceStreamGenerator(AppearanceStreamGenerator) is used. Appearance stream generation fallbacks to default rendering if annotation has no appearance stream generator set.


Note: This does not automatically remove existing appearance streams. The appearance stream only gets generated when the annotation has been modified or when calling generateAppearanceStream() explicitly.

Parameters
appearanceStreamGenerator Appearance stream generator.
addFirst Adds appearance stream generator to the beginning of the list. It will be used before any registered generator.

public abstract void addOnAnnotationUpdatedListener (AnnotationProvider.OnAnnotationUpdatedListener updatedListener)

Adds an AnnotationProvider.OnAnnotationUpdatedListener for being notified of updates to annotations. If the listener has already been added previously, this method will be a no-op. Passing null is not allowed and will result in an exception.

Parameters
updatedListener AnnotationProvider.OnAnnotationUpdatedListener that should be notified. Must be non-null.

public abstract void appendAnnotationState (Annotation annotation, AnnotationStateChange annotationStateChange)

Appends a new annotation state for the given annotation (adds it to the review history).

Parameters
annotation Annotation for which to set the state.
annotationStateChange New annotation state to be set.

public abstract Completable appendAnnotationStateAsync (Annotation annotation, AnnotationStateChange annotationStateChange)

Appends a new annotation state for the given annotation asynchronously (adds it to the review history).

Parameters
annotation Annotation for which to set the state.
annotationStateChange New annotation state to be set.
Returns
  • A Completable that completes once the annotation state has been appended.

public abstract Annotation createAnnotationFromInstantJson (String annotationJson)

Creates an annotation from the Instant JSON annotation format. The JSON must contain the type, the page number and any other required properties for that type. The created annotation will be automatically added to the document, and any registered AnnotationProvider.OnAnnotationUpdatedListener will be notified of the creation.

Parameters
annotationJson Instant JSON representation of the annotation to be created.
Returns
  • Annotation created from the provided Instant JSON. If creation of the annotation from JSON failed, this method throws an exception.
See Also

public abstract Single<Annotation> createAnnotationFromInstantJsonAsync (String annotationJson)

Creates an annotation from the Instant JSON annotation format asynchronously. The JSON must contain the type, the page number and any other required properties for that type. The created annotation will be automatically added to the document, and any registered AnnotationProvider.OnAnnotationUpdatedListener will be notified of the creation.

Parameters
annotationJson Instant JSON representation of the annotation to be created.
Returns
  • Single emitting annotation imported from provided Instant JSON or an error if creation of the annotation from JSON failed.
See Also

public abstract Observable<Annotation> getAllAnnotationsOfType (EnumSet<AnnotationType> types, int startIndex, int pageCount)

Returns all annotations of passed types in the specified page index range.

WARNING: Parsing all annotations in a document can take some time and is thus only available as an asynchronous call. If you have to use it as a synchronous call, use .toList().toBlocking() call.

Parameters
types Annotation types to return. ALL_ANNOTATION_TYPES can be used as a shorthand parameter for all annotations.
startIndex Index of the page to start the search.
pageCount Number of pages to be included, starting the count with the startIndex page.
Returns
  • Observable emitting all annotations of passed types in a document.

public abstract Observable<Annotation> getAllAnnotationsOfType (EnumSet<AnnotationType> types)

Returns all annotations of passed types in this document.

WARNING: Parsing all annotations in a document can take some time and is thus only available as an asynchronous call. If you have to use it as a synchronous call, use .toList().toBlocking() call.

Parameters
types Annotation types to return. ALL_ANNOTATION_TYPES can be used as a shorthand parameter for all annotations.
Returns
  • Observable emitting all annotations of passed types in a document.

public abstract Annotation getAnnotation (int pageIndex, int objectNumber)

Returns annotation with certain object ID on the page if it exists.

Note: this call may block for a while and should not be invoked on the main thread.

Parameters
pageIndex Page index of the page where the annotation is.
objectNumber Object number of the annotation to retrieve.
Returns
  • The requested annotation or null if not found.

public abstract Maybe<Annotation> getAnnotationAsync (int pageIndex, int objectNumber)

Returns annotation with certain object ID on the page if it exists, asynchronously.

Parameters
pageIndex Page index of the page where the annotation is.
objectNumber Object number of the annotation to retrieve.
Returns
  • An instance of Maybe that either emits the requested annotation in `onSuccess()` or terminates with `onCompleted()` or `onError()`.

public abstract List<Annotation> getAnnotationReplies (Annotation annotation)

Get all first-level replies to a particular annotation. First-level replies are annotations that return the given annotation via getInReplyTo(). The sort order is determined by the creation date.

Parameters
annotation Annotation whose replies we're fetching.
Returns
  • List of top-level replies to the given annotation, or an empty list if none are available.

public abstract Single<List<Annotation>> getAnnotationRepliesAsync (Annotation annotation)

Get all first-level replies to a particular annotation asynchronously. First-level replies are annotations that return the given annotation via getInReplyTo(). The sort order is determined by the creation date.

Parameters
annotation Annotation whose replies we're fetching.
Returns
  • Single that emits a list of first-level replies to the given annotation.

public abstract List<Annotation> getAnnotations (Collection<Integer> objectNumbers)

Returns annotations with given object numbers.

Parameters
objectNumbers Collection of object numbers to search for.
Returns
  • List of resolved annotations.

public abstract List<Annotation> getAnnotations (int pageIndex)

Returns a list of annotations on the page. For annotations not currently recognised and handled by PSPDFKit this returns UnknownAnnotation.

Note: this call may block for a while and should not be invoked on the main thread.

Parameters
pageIndex 0-indexed page number.
Returns
  • List of annotations on the page with the given page number.

public abstract Observable<List<Annotation>> getAnnotationsAsync (int pageIndex)

Returns list of annotations on the page. For annotations not currently recognised and handled by PSPDFKit this returns UnknownAnnotation.

Parameters
pageIndex 0-indexed page number.
Returns
  • Observable stream of annotations on page.

public abstract Observable<List<Annotation>> getAnnotationsAsync (Collection<Integer> objectNumbers)

Returns annotations with given object numbers, asynchronously.

Parameters
objectNumbers Collection of object numbers to search for.
Returns
  • Observable emitting list of found annotations.

public abstract List<Annotation> getFlattenedAnnotationReplies (Annotation annotation)

Get all flattened replies (all replies included but no nesting) to a particular annotation. The sort order is determined by the creation date.

Parameters
annotation Annotation whose replies we're fetching.
Returns
  • List all replies (flattened) to the given annotation, or an empty list if none are available.

public abstract Single<List<Annotation>> getFlattenedAnnotationRepliesAsync (Annotation annotation)

Get all flattened replies (all replies included but no nesting) to a particular annotation asynchronously. The sort order is determined by the creation date.

Parameters
annotation Annotation whose replies we're fetching.
Returns
  • Single that emits a list of all replies (flattened) to the given annotation.

public abstract List<AnnotationStateChange> getReviewHistory (Annotation annotation)

Get the review history of an annotation. The review history of an annotation is the list of states it has passed, for example, "Accepted", "Cancelled", and so on. This list is ordered chronologically, where the last element is the most current one according to the creation date of the annotation change.

Parameters
annotation Annotation for which to retrieve the review history.
Returns
  • List of annotation state changes ordered chronologically.

public abstract Single<List<AnnotationStateChange>> getReviewHistoryAsync (Annotation annotation)

Get the review history of an annotation asynchronously. The review history of an annotation is the list of states it has passed, for example, "Accepted", "Cancelled", and so on. This list is ordered chronologically, where the last element is the most current one according to the creation date of the annotation change.

Parameters
annotation Annotation for which to retrieve the review history.
Returns
  • Single emitting a list of annotation state changes ordered chronologically.

public abstract AnnotationReviewSummary getReviewSummary (Annotation annotation, String currentUser)

Get a summary information about the given annotation's review state.

Parameters
annotation Annotation for which to get the review summary.
currentUser The name of the current user, null to avoid including the current user into the review summary.
Returns
  • Annotation review summary, or null if it could not be retrieved.

public abstract Maybe<AnnotationReviewSummary> getReviewSummaryAsync (Annotation annotation, String currentUser)

Get a summary information about the given annotation's review state asynchronously.

Parameters
annotation Annotation for which to get the review summary.
currentUser The name of the current user, null to avoid including the current user into the review summary.
Returns
  • Maybe returning the given annotation review summary, or none if it could not be retrieved.

public abstract boolean hasUnsavedChanges ()

Returns whether there are unsaved changes to annotations in this document.

Returns
  • true if annotations were modified in this document and the document should be saved.

public abstract void removeAnnotationFromPage (Annotation annotation)

Removes annotation from the document. If the annotation is not attached to the document of this annotation provider, this will be a no-op.

Parameters
annotation Annotation to be removed from the document. May not be null.

public abstract Completable removeAnnotationFromPageAsync (Annotation annotation)

Removes annotation from this document asynchronously.

Parameters
annotation Annotation to be removed from the document.
Returns
  • Completable which has to be subscribed to for operation to run.

public abstract void removeAppearanceStreamGenerator (AppearanceStreamGenerator appearanceStreamGenerator)

Remove appearance stream generator that was previously added in addAppearanceStreamGenerator(AppearanceStreamGenerator).

public abstract void removeOnAnnotationUpdatedListener (AnnotationProvider.OnAnnotationUpdatedListener updatedListener)

Removes a previously added AnnotationProvider.OnAnnotationUpdatedListener. Upon calling this method the listener will no longer be notified of any changes. If the listener has not been added previously, this method will be a no-op. Passing null is not allowed, and will result in an exception.

Parameters
updatedListener AnnotationProvider.OnAnnotationUpdatedListener that should be removed. Must be non-null.