# 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/cos/example/usecases/`](https://github.com/zxfr/pd4ml-examples/tree/master/src/main/java/com/pd4ml/pdf/cos/example/usecases), and are ordinary runnable classes with a [`main(String[] args)`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/Main.html#main(java.lang.String[])). 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.cos.example.usecases.<ClassName> <args...>
```

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

| #  | Class                                         | Demonstrates                                                                                                                       |
| -- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 01 | [`Ex01_ParsingAndCatalog`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/cos/example/usecases/Ex01_ParsingAndCatalog.java)                      | The minimal call: parse a PDF, walk trailer to Root (the Catalog). Start here.                                                     |
| 02 | [`Ex02_CosPathQueries`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/cos/example/usecases/Ex02_CosPathQueries.java)                         | The COS-path query language: `/Root/...`, `[N]` array indexing, `evaluate` vs. `evaluateStrict`.                                   |
| 03 | [`Ex03_ListingObjectsAndPages`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/cos/example/usecases/Ex03_ListingObjectsAndPages.java)                 | Enumerating every indirect object, and walking the page tree by index.                                                             |
| 04 | [`Ex04_IncrementalUpdateEditing`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/cos/example/usecases/Ex04_IncrementalUpdateEditing.java)               | Editing an existing PDF as a real incremental update via [`IncrementalUpdateWriter`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/writer/IncrementalUpdateWriter.html) -- the same mechanism signing and LTV build on. |
| 05 | [`Ex05_ReadingEncryptedPdf`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/cos/example/usecases/Ex05_ReadingEncryptedPdf.java)                    | Reading an encrypted PDF: transparent decryption once given the right password.                                                    |
| 06 | [`Ex06_FiltersAndDecodedStreams`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/cos/example/usecases/Ex06_FiltersAndDecodedStreams.java)               | [`COSStream.getDecodedBytes()`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/COSStream.html#getDecodedBytes())/[`isFullyDecodable()`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/COSStream.html#isFullyDecodable()) and the `/Filter` chain.                                                        |
| 07 | [`Ex07_BuildingAndWritingADocumentFromScratch`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/cos/example/usecases/Ex07_BuildingAndWritingADocumentFromScratch.java) | Building a PDF entirely from the COS object model, then serializing it with [`COSDocumentWriter`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/writer/COSDocumentWriter.html) -- no template, no other library.  |
| 08 | [`Ex08_ErrorHandlingAndRecovery`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/cos/example/usecases/Ex08_ErrorHandlingAndRecovery.java)               | [`COSParseException`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/parser/COSParseException.html) for genuinely unparseable input, versus the brute-force recovery scan for a corrupt-but-recoverable one.       |

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

## See also

* [PD4ML COS API Manual](pd4ml-cos-api-manual) -- the programmer's manual behind these examples.
* [pd4coscli Reference](pd4coscli-reference) -- command-line reference for `com.pd4ml.pdf.cos.cli.CosCli`.
* [PD4ML Signing Manual](../pd4ml-pdf-signing/pd4ml-signing-manual) / [PD4ML Signing Examples](../pd4ml-pdf-signing/pd4ml-signing-examples) -- [`com.pd4ml.pdf.sign`](https://pd4ml.com/javadoc/com/pd4ml/pdf/sign/package-summary.html), digital signing built on this same foundation.
* [PD4ML PDF Merge Manual](../pd4ml-pdf-merge/pd4ml-merge-manual) / [PD4ML Merge Examples](../pd4ml-pdf-merge/pd4ml-merge-examples) -- combining page ranges from multiple PDFs.
* [PD4ML PDF Optimizer Manual](../pd4ml-pdf-optimizer/pd4ml-optimize-manual) / [PD4ML Optimizer Examples](../pd4ml-pdf-optimizer/pd4ml-optimize-examples) -- cleaning up unreferenced objects and incremental-update history.
* [PD4ML XFDF Manual](../pd4ml-pdf-xfdf/pd4ml-xfdf-manual) / [PD4ML XFDF Examples](../pd4ml-pdf-xfdf/pd4ml-xfdf-examples) -- [`com.pd4ml.pdf.xfdf`](https://pd4ml.com/javadoc/com/pd4ml/pdf/xfdf/package-summary.html), importing/exporting annotations and form field values, also built on this same foundation.