# Examples

_Available starting from PD4ML v4.1.1_

All examples are part of the public [`pd4ml-examples`](https://github.com/zxfr/pd4ml-examples) repository on GitHub, under [`src/main/java/com/pd4ml/pdf/merge/example/usecases/`](https://github.com/zxfr/pd4ml-examples/tree/master/src/main/java/com/pd4ml/pdf/merge/example/usecases), and are ordinary runnable classes with a `main(String[] args)`. Clone the repository; easiest from an IDE: right-click the class, Run. From the command line:

```bash
git clone https://github.com/zxfr/pd4ml-examples.git
cd pd4ml-examples
mvn compile dependency:build-classpath -Dmdep.outputFile=cp.txt
java -cp "target/classes;$(cat cp.txt)" \
     com.pd4ml.pdf.merge.example.usecases.<ClassName> <args...>
```

Every example builds its own small sample PDF(s) in memory (no external fixture files needed) and was actually run end-to-end -- these aren't untested snippets.

| #  | Class                               | Demonstrates                                                                                                                 |
| -- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| 01 | [`Ex01_BasicTwoSourceMerge`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/merge/example/usecases/Ex01_BasicTwoSourceMerge.java)          | The minimal call: select a page range from two sources and merge them. Start here.                                           |
| 02 | [`Ex02_PageRangeGrammar`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/merge/example/usecases/Ex02_PageRangeGrammar.java)             | The full page-range grammar: `N`, `N-M` (descending too), `N+`, and `odd`/`even` as suppressing filters, with deduplication. |
| 03 | [`Ex03_SingleSourceFilterAndReorder`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/merge/example/usecases/Ex03_SingleSourceFilterAndReorder.java) | With exactly one source, [`selectPages(...)`](https://pd4ml.com/javadoc/com/pd4ml/pdf/merge/PdfMergeSource.html#selectPages(java.lang.String)) doubles as a filter/reorder pass, not just a subset tool.                        |
| 04 | [`Ex04_SharedResourceDeduplication`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/merge/example/usecases/Ex04_SharedResourceDeduplication.java)  | Two pages of the same source sharing one font object are cloned exactly once in the output.                                  |
| 05 | [`Ex05_EncryptedSourceMerging`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/merge/example/usecases/Ex05_EncryptedSourceMerging.java)       | Merging an encrypted source alongside a plain one -- transparent decryption via `addSource`'s password.                      |
| 06 | [`Ex06_EncryptOutput`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/merge/example/usecases/Ex06_EncryptOutput.java)                | Encrypting the merged output, via the AES-256 shortcut or full [`PdfEncryptor.Options`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/security/PdfEncryptor.Options.html) control.                               |
| 07 | [`Ex07_TaggingReconciliation`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/merge/example/usecases/Ex07_TaggingReconciliation.java)        | Merging a tagged source with an untagged one -- best-effort `/StructTreeRoot` reconciliation.                                |
| 08 | [`Ex08_ErrorHandlingPatterns`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/merge/example/usecases/Ex08_ErrorHandlingPatterns.java)        | Every [`PdfMergeException`](https://pd4ml.com/javadoc/com/pd4ml/pdf/merge/PdfMergeException.html) failure mode and how to recognize it.                                                              |

For a ready-made command-line tool covering the same ground without writing any code, see the [pd4mergecli Reference](pd4mergecli-reference) and run [`com.pd4ml.pdf.merge.cli.Pd4MergeCli`](https://pd4ml.com/javadoc/com/pd4ml/pdf/merge/cli/Pd4MergeCli.html).

## See also

* [PD4ML PDF Merge Manual](pd4ml-merge-manual) -- the programmer's manual behind these examples.
* [pd4mergecli Reference](pd4mergecli-reference) -- command-line reference for `com.pd4ml.pdf.merge.cli.Pd4MergeCli`.
* [PD4ML COS API Manual](../pd4ml-pdf-cos/pd4ml-cos-api-manual) / [PD4ML COS Examples](../pd4ml-pdf-cos/pd4ml-cos-examples) -- standalone [`com.pd4ml.pdf.cos`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/package-summary.html) foundation this package is built on.
* [pd4coscli Reference](../pd4ml-pdf-cos/pd4coscli-reference) -- command-line reference for [`com.pd4ml.pdf.cos.cli.CosCli`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/cli/CosCli.html).
* [PD4ML PDF Optimizer Manual](../pd4ml-pdf-optimizer/pd4ml-optimize-manual) / [PD4ML Optimizer Examples](../pd4ml-pdf-optimizer/pd4ml-optimize-examples) -- a natural next step after merging: clean up the result.
* [PD4ML XFDF Manual](../pd4ml-pdf-xfdf/pd4ml-xfdf-manual) / [PD4ML XFDF Examples](../pd4ml-pdf-xfdf/pd4ml-xfdf-examples) -- another natural next step: bring in reviewers' annotations and form field values from an XFDF file.