# 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/xfdf/example/usecases/`](https://github.com/zxfr/pd4ml-examples/tree/master/src/main/java/com/pd4ml/pdf/xfdf/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.xfdf.example.usecases.<ClassName> <args...>
```

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

| #  | Class                               | Demonstrates                                                                                                                 |
| -- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| 01 | [`Ex01_BasicExportAndImport`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/xfdf/example/usecases/Ex01_BasicExportAndImport.java)         | The minimal round trip: export a PDF's annotations to XFDF, then import that XFDF into a different PDF. Start here.          |
| 02 | [`Ex02_InspectingTheParsedModel`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/xfdf/example/usecases/Ex02_InspectingTheParsedModel.java)     | [`XfdfReader.read(...)`](https://pd4ml.com/javadoc/com/pd4ml/pdf/xfdf/XfdfReader.html#read(byte[])) turns XFDF bytes into a plain [`XfdfDocument`](https://pd4ml.com/javadoc/com/pd4ml/pdf/xfdf/XfdfDocument.html)/[`XfdfAnnotation`](https://pd4ml.com/javadoc/com/pd4ml/pdf/xfdf/XfdfAnnotation.html) model you can inspect directly.         |
| 03 | [`Ex03_UpdateIfExistsSwitch`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/xfdf/example/usecases/Ex03_UpdateIfExistsSwitch.java)         | `Options.updateIfExists(boolean)` -- update a matching annotation in place vs. always adding a new one.                      |
| 04 | [`Ex04_FormFieldValues`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/xfdf/example/usecases/Ex04_FormFieldValues.java)              | Form field values travel through `<fields>`, only ever updating an existing AcroForm field -- including checkbox `/AS` sync. |
| 05 | [`Ex05_TypeAndIdFiltering`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/xfdf/example/usecases/Ex05_TypeAndIdFiltering.java)           | `Options.types(String)`/`ids(String)` restrict export or import to a comma-separated subset.                                 |
| 06 | [`Ex06_EncryptedSourceExport`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/xfdf/example/usecases/Ex06_EncryptedSourceExport.java)        | Exporting from an encrypted PDF -- transparent decryption via the password overload.                                         |
| 07 | [`Ex07_PostImportOptimizeAndEncrypt`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/xfdf/example/usecases/Ex07_PostImportOptimizeAndEncrypt.java) | `Options.optimizeOutput(boolean)` + [`encryptOutput(...)`](https://pd4ml.com/javadoc/com/pd4ml/pdf/xfdf/XfdfImporter.Options.html#encryptOutput(com.pd4ml.pdf.cos.security.PdfEncryptor.Options)) chained after an import.                                            |
| 08 | [`Ex08_ErrorHandlingPatterns`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/xfdf/example/usecases/Ex08_ErrorHandlingPatterns.java)        | Every [`XfdfException`](https://pd4ml.com/javadoc/com/pd4ml/pdf/xfdf/XfdfException.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 [pd4xfdfcli Reference](pd4xfdfcli-reference) and run [`com.pd4ml.pdf.xfdf.cli.Pd4XfdfCli`](https://pd4ml.com/javadoc/com/pd4ml/pdf/xfdf/cli/Pd4XfdfCli.html).

## See also

* [PD4ML XFDF Manual](pd4ml-xfdf-manual) -- the programmer's manual behind these examples.
* [pd4xfdfcli Reference](pd4xfdfcli-reference) -- command-line reference for `com.pd4ml.pdf.xfdf.cli.Pd4XfdfCli`.
* [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 Merge Manual](../pd4ml-pdf-merge/pd4ml-merge-manual) / [PD4ML Merge Examples](../pd4ml-pdf-merge/pd4ml-merge-examples) -- combining page ranges from several PDFs, a natural companion to annotation import/export.
* [PD4ML PDF Optimizer Manual](../pd4ml-pdf-optimizer/pd4ml-optimize-manual) -- `Options.optimizeOutput(boolean)` delegates here.
* [PD4ML Signing Manual](../pd4ml-pdf-signing/pd4ml-signing-manual) -- [`com.pd4ml.pdf.sign`](https://pd4ml.com/javadoc/com/pd4ml/pdf/sign/package-summary.html), which shares the same `com.pd4ml.pdf.cos` foundation and, via [`com.pd4ml.pdf.cos.security`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/security/package-summary.html), the same [`PdfEncryptor`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/security/PdfEncryptor.html) this package's output encryption uses.