Lazy Load PDF Annotations in Swift for iOS

1
//
2
//  Copyright © 2021-2025 PSPDFKit GmbH. All rights reserved.
3
//
4
//  The Nutrient sample applications are licensed with a modified BSD license.
5
//  Please see License for details. This notice may not be removed from this file.
6
//
7

8
import PSPDFKit
9
import PSPDFKitUI
10

11
class CompoundAnnotationProviderExample: Example {
12

13
    override init() {
14
        super.init()
15
        title = "Compound Annotation Provider"
16
        contentDescription = "A custom annotation provider that lazily loads its annotations and combines them with annotations from the PDF document."
17
        category = .annotationProviders
18
    }
19

20
    override func invoke(with delegate: ExampleRunnerDelegate) -> UIViewController? {
21
        let document = AssetLoader.writableDocument(for: .welcome, overrideIfExists: true)
22
        document.didCreateDocumentProviderBlock = { documentProvider in
23
            if let fileAnnotationProvider = documentProvider.annotationManager.fileAnnotationProvider {
24
                documentProvider.annotationManager.annotationProviders = [
25
                    CompoundAnnotationProvider(documentProvider: documentProvider, fileAnnotationProvider: fileAnnotationProvider),
26
                ]
27
            }
28
        }
29
        return AdaptivePDFViewController(document: document)
30
    }
31

32
}
33

34
private class CompoundAnnotationProvider: PDFContainerAnnotationProvider {
35

36
    init(documentProvider: PDFDocumentProvider, fileAnnotationProvider: PDFFileAnnotationProvider) {
37
        self.fileAnnotationProvider = fileAnnotationProvider
38
        super.init(documentProvider: documentProvider)
39
    }
40

41
    /// Reference to the original file annotation provider.
42
    let fileAnnotationProvider: PDFFileAnnotationProvider
43

44
    /// Page indices for which we have lazily loaded the annotations.
45
    var loadedPageIndices: Set<PageIndex> = []
46

47
    override func annotationsForPage(at pageIndex: PageIndex) -> [Annotation]? {
48
        // First, fetch the annotations from the file annotation provider. Use
49
        // `annotationsForPage(at:)` because this is the function that actually
50
        // loads the annotations.
51
        let fileAnnotations = fileAnnotationProvider.annotationsForPage(at: pageIndex) ?? []
52
        // Then, merge them with the custom annotations.
53
        let customAnnotations = customAnnotationsForPage(at: pageIndex)
54
        return fileAnnotations + customAnnotations
55
    }
56

57
    private func customAnnotationsForPage(at pageIndex: PageIndex) -> [Annotation] {
58
        // If we loaded our custom annotations into the cache, ask `super` to
59
        // retrieve them from cache within the same critical region for reading
60
        // to achieve atomicity.
61
        let cachedCustomAnnotations = performRead {
62
            loadedPageIndices.contains(pageIndex) ? super.annotationsForPage(at: pageIndex) : nil
63
        }
64
        if let cachedCustomAnnotations {
65
            return cachedCustomAnnotations
66
        }
67
        // Otherwise, we need to load the custom annotations and load them
68
        // into the cache. We need to do all that within a critical region.
69
        return performWriteAndWait {
70
            // Because we had to leave the critical region from reading to
71
            // writing, another thread could have raced here before us. In order
72
            // to prevent caching the same custom annotations multiple times, we
73
            // must check our bookkeeping first. Reads can be nested in writes,
74
            // so calling `super` here is fine.
75
            if loadedPageIndices.contains(pageIndex) {
76
                let cachedCustomAnnotations = super.annotationsForPage(at: pageIndex) ?? []
77
                return cachedCustomAnnotations
78
            }
79
            // For the sake of this example, we simulate loading annotations by
80
            // generating random squares.
81
            let loadedCustomAnnotations = makeSquares(at: pageIndex)
82
            // Because adding annotations to the cache can fail and the return
83
            // value can differ, we need to account for that when doing our
84
            // bookkeeping.
85
            guard let addedCustomAnnotations = super.add(loadedCustomAnnotations, options: nil) else {
86
                return []
87
            }
88
            // Now that we know caching succeeded, do the bookkeeping and return
89
            // the added custom annotations.
90
            loadedPageIndices.insert(pageIndex)
91
            return addedCustomAnnotations
92
        }
93
    }
94

95
    override func add(_ annotations: [Annotation], options: [AnnotationManager.ChangeBehaviorKey: Any]? = nil) -> [Annotation]? {
96
        // For each annotation being added here, make sure we have loaded the
97
        // custom annotations at the page they're supposed to be on.
98
        for annotation in annotations {
99
            _ = customAnnotationsForPage(at: annotation.pageIndex)
100
        }
101
        return super.add(annotations, options: options)
102
    }
103

104
    override var allowAnnotationZIndexMoves: Bool {
105
        // Because this annotation provider merges annotations from two sources,
106
        // z-index moves could have unreliable results. It's better to disable
107
        // them altogether.
108
        false
109
    }
110

111
    override func insert(_ annotation: Annotation, atZIndex destinationIndex: UInt, options: [AnnotationManager.ChangeBehaviorKey: Any]? = nil) throws {
112
        // Since z-index moves are disabled, we should always throw here.
113
        throw PSPDFKitError(.cannotModifyAnnotationZIndices)
114
    }
115

116
    override var shouldSaveAnnotations: Bool {
117
        // Because this implementation doesn't actually load annotations from
118
        // any store, we don't support saving.
119
        false
120
    }
121

122
    override func saveAnnotations(options: [String: Any]? = nil) throws {
123
        // Since saving is disabled, we should always throw here.
124
        throw PSPDFKitError(.annotationSavingDisabled)
125
        // If your custom annotation store supports wtiting on a per-page basis,
126
        // and you don't do that immediately when adding annotations, you will
127
        // have to make sure that the custom annotations for all pages have been
128
        // cached before. In any case, any actual saving operation would need to
129
        // be wrapped in its entirety in a critical region for writing, using
130
        // `performWriteAndWait`.
131
    }
132

133
}
134

135
private func makeSquares(at pageIndex: PageIndex) -> [SquareAnnotation] {
136
    let left = SquareAnnotation()
137
    left.color = .systemRed
138
    left.fillColor = .systemTeal
139
    left.boundingBox = CGRect(x: 50, y: 50, width: 100, height: 100)
140
    left.pageIndex = pageIndex
141
    let right = SquareAnnotation()
142
    right.color = .systemGreen
143
    right.fillColor = .systemPink
144
    right.boundingBox = CGRect(x: 200, y: 50, width: 100, height: 100)
145
    right.pageIndex = pageIndex
146
    return [left, right]
147
}