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

Every example was compiled against real BouncyCastle classes and, except where noted (live network calls, or a real PKCS#11 token this environment doesn't have), run end-to-end to produce a real signed PDF -- these aren't untested snippets.

| #  | Class                             | Demonstrates                                                                                                          |
| -- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| 01 | [`Ex01_InvisibleSigningBasic`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex01_InvisibleSigningBasic.java)      | The minimal call: PKCS#12 key, invisible signature. Start here.                                                       |
| 02 | [`Ex02_VisibleSignatureWithText`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex02_VisibleSignatureWithText.java)   | A visible widget with wrapped text only, built-in Helvetica metrics.                                                  |
| 03 | [`Ex03_VisibleSignatureWithImage`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex03_VisibleSignatureWithImage.java)  | A visible widget with a stamp image (PNG/JPEG) plus a text caption.                                                   |
| 04 | [`Ex04_DigestAlgorithmChoice`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex04_DigestAlgorithmChoice.java)      | Choosing SHA-256 / SHA-384 / SHA-512; algorithm auto-derived from key type.                                           |
| 05 | [`Ex05_RfcTimestamping`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex05_RfcTimestamping.java)            | RFC 3161 trusted timestamp from a TSA, with optional Basic Auth.                                                      |
| 06 | [`Ex06_DocMdpCertificationLevels`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex06_DocMdpCertificationLevels.java)  | PDF "Certify" at all three DocMDP levels (P=1/2/3).                                                                   |
| 07 | [`Ex07_CoSigningExistingDocument`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex07_CoSigningExistingDocument.java)  | Two independent signers on the same (uncertified) document.                                                           |
| 08 | [`Ex08_Pkcs11HsmSigning`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex08_Pkcs11HsmSigning.java)           | Signing with a PKCS#11 hardware token/HSM -- key never leaves the token.                                              |
| 09 | [`Ex09_CloudKmsSigning`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex09_CloudKmsSigning.java)            | The [`RemoteSigner`](https://pd4ml.com/javadoc/com/pd4ml/pdf/sign/RemoteSigner.html) seam for cloud KMS (AWS/Azure/GCP), with a real AWS KMS sketch in comments.                        |
| 10 | [`Ex10_CustomPlaceholderSize`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex10_CustomPlaceholderSize.java)      | Sizing the `/Contents` placeholder for a long chain + timestamp; the resulting error if it's too small.               |
| 11 | [`Ex11_CustomFieldName`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex11_CustomFieldName.java)            | Naming the AcroForm signature field explicitly.                                                                       |
| 12 | [`Ex12_StreamBasedSigning`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex12_StreamBasedSigning.java)         | The three equivalent call shapes: `File`, `InputStream`/`OutputStream`, `byte[]`.                                     |
| 13 | [`Ex13_LtvImmediatelyAfterSigning`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex13_LtvImmediatelyAfterSigning.java) | Sign, then add PAdES-LT validation info in the same process.                                                          |
| 14 | [`Ex14_LtvOnExistingSignedPdf`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex14_LtvOnExistingSignedPdf.java)     | Add LTV to a PDF signed earlier/elsewhere -- chain recovered from the CMS itself, no original signing context needed. |
| 15 | [`Ex15_ErrorHandlingPatterns`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex15_ErrorHandlingPatterns.java)      | Every [`PdfSigningException`](https://pd4ml.com/javadoc/com/pd4ml/pdf/sign/PdfSigningException.html) failure mode and how to recognize it.                                                     |
| 16 | [`Ex16_FullyLoadedCombinedExample`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex16_FullyLoadedCombinedExample.java) | Every major option combined: visible + certify + timestamp + LTV.                                                     |
| 17 | [`Ex17_CosInspectionAndPathQuery`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex17_CosInspectionAndPathQuery.java)  | Using [`com.pd4ml.pdf.cos`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/package-summary.html) alone (no signing) to parse and COS-path-query a PDF.                                       |
| 18 | [`Ex18_ListSignatureFields`](https://github.com/zxfr/pd4ml-examples/blob/master/src/main/java/com/pd4ml/pdf/sign/example/usecases/Ex18_ListSignatureFields.java)        | Programmatically enumerating signature fields and their metadata.                                                     |

See also `com.pd4ml.pdf.sign.example.SignPdfExample` (`src/test/java/com/pd4ml/pdf/sign/example/SignPdfExample.java`) -- the original minimal single-file CLI sample (PKCS#12 + optional TSA only, real files expected), kept for the simplest possible reference.

For a ready-made command-line tool covering the same ground without writing any code, see the [pdfsigncli Reference](pd4signcli-reference) and run [`com.pd4ml.pdf.sign.cli.PdfSignCli`](https://pd4ml.com/javadoc/com/pd4ml/pdf/sign/cli/PdfSignCli.html). For `com.pd4ml.pdf.cos` alone -- inspection, COS-path queries, object listing, and incremental-update editing, with no signing involved -- see the [pd4coscli Reference](../pd4ml-pdf-cos/pd4coscli-reference) (and its own examples) and run [`com.pd4ml.pdf.cos.cli.CosCli`](https://pd4ml.com/javadoc/com/pd4ml/pdf/cos/cli/CosCli.html).

## See also

* [PD4ML Signing Manual](pd4ml-signing-manual) -- the programmer's manual behind these examples.
* [pdfsigncli Reference](pd4signcli-reference) -- command-line reference for `com.pd4ml.pdf.sign.cli.PdfSignCli`.
* [PD4ML COS API Manual](../pd4ml-pdf-cos/pd4ml-cos-api-manual) -- standalone `com.pd4ml.pdf.cos` programmer's manual.
* [PD4ML COS Examples](../pd4ml-pdf-cos/pd4ml-cos-examples) -- runnable `com.pd4ml.pdf.cos` use-case examples.
* [PD4ML Merge Examples](../pd4ml-pdf-merge/pd4ml-merge-examples) / [PD4ML Optimizer Examples](../pd4ml-pdf-optimizer/pd4ml-optimize-examples) -- the same style of runnable examples for [`com.pd4ml.pdf.merge`](https://pd4ml.com/javadoc/com/pd4ml/pdf/merge/package-summary.html) / [`com.pd4ml.pdf.optimizer`](https://pd4ml.com/javadoc/com/pd4ml/pdf/optimizer/package-summary.html).
* [PD4ML XFDF Examples](../pd4ml-pdf-xfdf/pd4ml-xfdf-examples) -- the same style of runnable examples for [`com.pd4ml.pdf.xfdf`](https://pd4ml.com/javadoc/com/pd4ml/pdf/xfdf/package-summary.html) (annotation/form field import and export).