PD4ML PDF Merge

PD4ML PDF Merge combines pages from one or more existing PDF files into a single new PDF. For each source you choose which pages to take and in which order, with a short page-range string such as "2-5,8,10-12" or "1+,odd". The tool works on finished PDF files, not on HTML: use it to assemble documents from parts, cut a document down to the pages you need, or write an unencrypted copy of a protected PDF you have the password for. It is available as a Java API, com.pd4ml.pdf.merge, and as a command-line tool, pd4mergecli.

What you can do with it

• Select page ranges per source: single pages (N), ranges (N-M, also descending, e.g. 5-2), open ranges to the last page (N+), and odd/even as filters over the other tokens. A page selected twice appears once, at its first position.
• Merge any number of sources: pages appear in the order the sources were added, and within a source in the order its range string lists them.
• Read encrypted sources: pass the user or owner password with the source; an empty password is tried as well.
• Encrypt the output: AES-256 with a user and an owner password, or a choice of RC4_128, AES_128 or AES_256 together with raw /P permission bits.
• Filter, reorder or decrypt a single PDF: with exactly one source, the page selection is optional; without it the output holds all pages of the source, decrypted unless output encryption is set.
• Keep tagging where it exists: the structure trees of tagged sources are merged into one /StructTreeRoot; structure elements that span excluded pages are pruned.
• Write compact output: objects that several pages of one source share, such as fonts, are copied once, and the merged pages are grouped in a page tree of at most 10 kids per node.

Quick start

Take the odd pages of pages 2-5 of A.pdf, followed by pages 1, 3 and 6 to the last page of the password-protected B.pdf:

import com.pd4ml.pdf.merge.PdfMergeException;
import com.pd4ml.pdf.merge.PdfMerger;

import java.io.File;

public class MergeQuickStart {
    public static void main(String[] args) throws PdfMergeException {
        PdfMerger merger = new PdfMerger();
        merger.addSource(new File("A.pdf")).selectPages("2-5,odd");
        merger.addSource(new File("B.pdf"), "secret").selectPages("1,3,6+");
        merger.merge(new File("merged.pdf"));
    }
}

Every failure (a wrong password, a page out of range, a malformed source) is reported as a PdfMergeException. To get the result as a byte[] instead of a file, call mergeToBytes(); to encrypt it, call encryptOutput("openPassword", "ownerPassword") before merging.

The same merge from the command line:

java -cp pd4ml.jar com.pd4ml.pdf.merge.cli.Pd4MergeCli \
     --in=A.pdf --pages=2-5,odd \
     --in=B.pdf --password=secret --pages=1,3,6+ \
     --out=merged.pdf

When to use it

PD4ML's main API also combines documents: PdfDocument.append(...) and PdfDocument.mergePDFs(...) join two whole documents, and PD4ML.merge(...) puts one page range of an existing PDF before or after a conversion result. Both use PdfMerger internally. Use PD4ML PDF Merge directly when you need more than two sources, a page selection per source, odd/even filters or reordering, or encrypted sources and output.

In this section

• PD4ML PDF Merge API - Programmer's Manual: how a merge works, the PdfMerger and PdfMergeSource methods, the full page-range grammar, encryption, tagging reconciliation, error messages and limitations.
• Examples: eight runnable example classes from the pd4ml-examples repository, from a basic two-source merge to error handling.
• pd4mergecli Reference: invocation, flags, exit codes, examples and troubleshooting for the command-line tool.
• Javadoc: API reference of the com.pd4ml.pdf.merge package.