Package com.pspdfkit.document.formatters

Class DocumentJsonFormatter

  • All Implemented Interfaces:
    
public final class DocumentJsonFormatter

    Exports and imports changes made to annotations and form fields of a PdfDocument into a JSON string. JSON strings created and read by this class are also used by PSPDFKit Instant.

    The JSON generated by this class represents a set of all annotation, and form field changes to the original document (i.e. the document in the state in which it was loaded). It comprises all added annotations, changes to existing annotations, deleted annotations, and also values entered into form fields. More info on the JSON format is available in our online guides.

    One possible use case for using this is syncing changes made to the document without having to transmit the entire PDF document.

    • Constructor Detail

    • Method Detail

      • exportDocumentJson

         static void exportDocumentJson(@NonNull() PdfDocument document, @NonNull() OutputStream outputStream)

        Exports all (unsaved) changes to annotations, and form elements made since opening the given document into a JSON string. This JSON string contains a pdfId and can only be imported on the exact same document again. Trying to import it in a different document will throw a DocumentJsonFormatterException. One possible use case for document JSON is syncing document changes without having to send the entire PDF.

        The generated JSON is written to outputStream. Serialization is performed on the current thread. Avoid calling this method on the main thread and consider using exportDocumentJsonAsync instead to avoid that your application becomes unresponsive.

        The method will throw a DocumentJsonFormatterException when encountering an unexpected error while exporting the JSON.

        Exporting of compound documents changes is not supported. This method will throw an exception if called with a compound document (i.e. a document having more than one document source).

        Uses the latest Instant JSON protocol version. See exportDocumentJson to specify the version for compatibility with older clients.

        Parameters:
        document - The PdfDocument to serialize.
        outputStream - The OutputStream to which the JSON should be written.

      • exportDocumentJsonAsync

         static Completable exportDocumentJsonAsync(@NonNull() PdfDocument document, @NonNull() OutputStream outputStream)

        Asynchronously exports all (unsaved) changes to annotations, and form elements made since opening the given document into a JSON string. This JSON string contains a pdfId and can only be imported on the exact same document again. Trying to import it in a different document will throw a DocumentJsonFormatterException. One possible use case for document JSON is syncing document changes without having to send the entire PDF.

        The generated JSON is written to outputStream. Serialization will start upon subscribing to the Completable returned by this method. The returned completable does not operate on any particular scheduler. If you want to run the serialization process on a background thread, consider calling subscribeOn on the completable before subscribing.

        The returned completable will emit a DocumentJsonFormatterException when encountering an unexpected error while exporting the JSON.

        Exporting of compound documents is not supported. This method will throw an exception if called with a compound document (i.e. a document having more than one document source).

        Uses the latest Instant JSON protocol version. See exportDocumentJson to specify the version for compatibility with older clients.

        Parameters:
        document - The PdfDocument to serialize.
        outputStream - The OutputStream to which the JSON should be written.
        Returns:

        A Completable that will start the JSON export once its subscribe method is called.

      • importDocumentJson

         static void importDocumentJson(@NonNull() PdfDocument document, @NonNull() DataProvider dataProvider)

        Imports a document JSON and applies its changes to the given document. The JSON has to be provided by the given dataProvider. Deserialization is performed on the current thread. When trying to import from the main thread, consider using importDocumentJsonAsync instead to avoid that your application becomes unresponsive.

        The method will throw a DocumentJsonFormatterException when encountering an unexpected error while importing the JSON.

        Importing JSON to compound documents is not supported. This method will throw an exception if called with a compound document (i.e. a document having more than one document source).

        Parameters:
        document - The PdfDocument to which the JSON should be imported.
        dataProvider - The DataProvider which serves the document JSON.

      • importDocumentJsonAsync

         static Completable importDocumentJsonAsync(@NonNull() PdfDocument document, @NonNull() DataProvider dataProvider)

        Asynchronously imports a document JSON and applies its changes to the given document. The JSON has to be provided by the given dataProvider. Deserialization will start upon subscribing to the Completable returned by this method. The returned completable does not operate on any particular scheduler. If you want to run the deserialization process on a background thread, consider calling subscribeOn on the completable before subscribing.

        The returned completable will emit a DocumentJsonFormatterException when encountering an unexpected error while importing the JSON.

        Importing JSON to compound documents is not supported. This method will throw an exception if called with a compound document (i.e. a document having more than one document source).

        Parameters:
        document - The PdfDocument to which the JSON should be imported.
        dataProvider - The DataProvider which serves the document JSON.
        Returns:

        A Completable that will start the JSON import once its subscribe method is called.