0
# Multi-PDF Operations
1
2
Utilities for merging multiple PDF documents, splitting documents into separate files, and overlaying content between documents with flexible configuration options.
3
4
## PDF Merging
5
6
Combine multiple PDF documents into a single document with memory usage control.
7
8
```java { .api }
9
// Constructor in org.apache.pdfbox.multipdf.PDFMergerUtility
10
public PDFMergerUtility();
11
12
// Source management
13
public void addSource(File source) throws FileNotFoundException;
14
public void addSource(InputStream source);
15
public void addSources(List<InputStream> sourcesList);
16
17
// Destination configuration
18
public void setDestinationFileName(String destinationFileName);
19
public void setDestinationStream(OutputStream destinationStream);
20
public void setDestinationDocument(PDDocument destinationDocument);
21
22
// Merge execution
23
public void mergeDocuments() throws IOException;
24
public void mergeDocuments(MemoryUsageSetting memUsageSetting) throws IOException;
25
26
// Page range control
27
public void setStartPage(int startPage);
28
public void setEndPage(int endPage);
29
```
30
31
## PDF Splitting
32
33
Split a PDF document into separate documents based on various criteria.
34
35
```java { .api }
36
// Constructor in org.apache.pdfbox.multipdf.Splitter
37
public Splitter();
38
39
// Configuration methods
40
public void setSplitAtPage(int splitAtPage);
41
public void setStartPage(int startPage);
42
public void setEndPage(int endPage);
43
public void setMemoryUsageSetting(MemoryUsageSetting memUsageSetting);
44
45
// Splitting execution
46
public List<PDDocument> split(PDDocument document) throws IOException;
47
48
// Page count control
49
protected boolean splitAtPage(int pageNumber);
50
```
51
52
## PDF Overlay
53
54
Overlay content from one PDF onto pages of another PDF with flexible positioning and page mapping.
55
56
```java { .api }
57
// Constructor in org.apache.pdfbox.multipdf.Overlay
58
public Overlay();
59
60
// Input document configuration
61
public void setInputPDF(PDDocument inputPDF);
62
public void setInputFile(String inputFile) throws IOException;
63
64
// Overlay document configuration
65
public void setDefaultOverlayPDF(PDDocument defaultOverlayPDF);
66
public void setDefaultOverlayFile(String defaultOverlayFile) throws IOException;
67
public void setFirstPageOverlayPDF(PDDocument firstPageOverlayPDF);
68
public void setFirstPageOverlayFile(String firstPageOverlayFile) throws IOException;
69
public void setLastPageOverlayPDF(PDDocument lastPageOverlayPDF);
70
public void setLastPageOverlayFile(String lastPageOverlayFile) throws IOException;
71
public void setOddPageOverlayPDF(PDDocument oddPageOverlayPDF);
72
public void setOddPageOverlayFile(String oddPageOverlayFile) throws IOException;
73
public void setEvenPageOverlayPDF(PDDocument evenPageOverlayPDF);
74
public void setEvenPageOverlayFile(String evenPageOverlayFile) throws IOException;
75
76
// Advanced overlay configuration
77
public void setOverlayPosition(Overlay.Position position);
78
public void setAllPagesOverlayPDF(PDDocument allPagesOverlayPDF);
79
public void setAllPagesOverlayFile(String allPagesOverlayFile) throws IOException;
80
81
// Execution
82
public PDDocument overlay(Map<Integer, String> specificPageOverlayFile) throws IOException;
83
```
84
85
## Memory Management
86
87
Control memory usage during multi-PDF operations.
88
89
```java { .api }
90
// Factory methods in org.apache.pdfbox.io.MemoryUsageSetting
91
public static MemoryUsageSetting setupMainMemoryOnly();
92
public static MemoryUsageSetting setupMainMemoryOnly(long maxMainMemoryBytes);
93
public static MemoryUsageSetting setupTempFileOnly();
94
public static MemoryUsageSetting setupMixed(long maxMainMemoryBytes);
95
public static MemoryUsageSetting setupMixed(long maxMainMemoryBytes, long maxStorageBytes);
96
```
97
98
## Overlay Positioning
99
100
Control overlay positioning on target pages.
101
102
```java { .api }
103
// Enum values in org.apache.pdfbox.multipdf.Overlay.Position
104
public static final Position FOREGROUND; // Overlay on top
105
public static final Position BACKGROUND; // Overlay behind content
106
```
107
108
## Usage Examples
109
110
### Basic PDF Merging
111
112
```java
113
PDFMergerUtility merger = new PDFMergerUtility();
114
115
// Add source documents
116
merger.addSource(new File("document1.pdf"));
117
merger.addSource(new File("document2.pdf"));
118
merger.addSource(new File("document3.pdf"));
119
120
// Set output destination
121
merger.setDestinationFileName("merged-document.pdf");
122
123
// Perform merge with memory optimization
124
MemoryUsageSetting memUsage = MemoryUsageSetting.setupTempFileOnly();
125
merger.mergeDocuments(memUsage);
126
```
127
128
### Merging with Page Ranges
129
130
```java
131
PDFMergerUtility merger = new PDFMergerUtility();
132
133
// Add first document (pages 1-5)
134
merger.addSource(new File("document1.pdf"));
135
merger.setStartPage(1);
136
merger.setEndPage(5);
137
138
// Add second document (pages 10-15)
139
merger.addSource(new File("document2.pdf"));
140
merger.setStartPage(10);
141
merger.setEndPage(15);
142
143
merger.setDestinationFileName("partial-merge.pdf");
144
merger.mergeDocuments();
145
```
146
147
### PDF Splitting
148
149
```java
150
PDDocument document = Loader.loadPDF(new File("large-document.pdf"));
151
152
Splitter splitter = new Splitter();
153
154
// Split every 10 pages
155
splitter.setSplitAtPage(10);
156
157
// Split with memory optimization
158
splitter.setMemoryUsageSetting(MemoryUsageSetting.setupTempFileOnly());
159
160
List<PDDocument> splitDocuments = splitter.split(document);
161
162
// Save split documents
163
for (int i = 0; i < splitDocuments.size(); i++) {
164
PDDocument splitDoc = splitDocuments.get(i);
165
splitDoc.save("split-part-" + (i + 1) + ".pdf");
166
splitDoc.close();
167
}
168
169
document.close();
170
```
171
172
### Custom Splitting Logic
173
174
```java
175
public class CustomSplitter extends Splitter {
176
@Override
177
protected boolean splitAtPage(int pageNumber) {
178
// Split at pages that are multiples of 5, but not 10
179
return (pageNumber % 5 == 0) && (pageNumber % 10 != 0);
180
}
181
}
182
183
PDDocument document = Loader.loadPDF(new File("document.pdf"));
184
CustomSplitter splitter = new CustomSplitter();
185
List<PDDocument> splitDocs = splitter.split(document);
186
// Handle split documents...
187
```
188
189
### PDF Overlay Operations
190
191
```java
192
Overlay overlay = new Overlay();
193
194
// Set input document
195
overlay.setInputFile("base-document.pdf");
196
197
// Set default overlay for all pages
198
overlay.setDefaultOverlayFile("watermark.pdf");
199
200
// Set specific overlays for first and last pages
201
overlay.setFirstPageOverlayFile("cover-overlay.pdf");
202
overlay.setLastPageOverlayFile("back-overlay.pdf");
203
204
// Set overlay position
205
overlay.setOverlayPosition(Overlay.Position.BACKGROUND);
206
207
// Create specific page overlays
208
Map<Integer, String> specificOverlays = new HashMap<>();
209
specificOverlays.put(3, "special-page-3-overlay.pdf");
210
specificOverlays.put(7, "special-page-7-overlay.pdf");
211
212
// Perform overlay
213
PDDocument result = overlay.overlay(specificOverlays);
214
result.save("overlaid-document.pdf");
215
result.close();
216
```
217
218
### Advanced Overlay Configuration
219
220
```java
221
Overlay overlay = new Overlay();
222
223
// Load documents programmatically
224
PDDocument inputDoc = Loader.loadPDF(new File("input.pdf"));
225
PDDocument watermarkDoc = Loader.loadPDF(new File("watermark.pdf"));
226
PDDocument headerDoc = Loader.loadPDF(new File("header.pdf"));
227
PDDocument footerDoc = Loader.loadPDF(new File("footer.pdf"));
228
229
overlay.setInputPDF(inputDoc);
230
overlay.setDefaultOverlayPDF(watermarkDoc);
231
overlay.setOddPageOverlayPDF(headerDoc);
232
overlay.setEvenPageOverlayPDF(footerDoc);
233
234
// Apply overlay
235
PDDocument result = overlay.overlay(new HashMap<>());
236
result.save("complex-overlay.pdf");
237
238
// Clean up
239
result.close();
240
inputDoc.close();
241
watermarkDoc.close();
242
headerDoc.close();
243
footerDoc.close();
244
```