# PD4ML PDF XFDF

PD4ML PDF XFDF moves review comments and form data in and out of existing PDF files. XFDF (ISO 19444-1) is an XML format that carries a PDF's annotations and form field values without the rest of the document. The `com.pd4ml.pdf.xfdf` package exports a PDF's markup annotations and AcroForm field values to an XFDF document, and imports an XFDF document's annotations and field values back into a PDF. The same operations are available from the command line with `pd4xfdfcli`.

{% hint style="version" %}
Available from **PD4ML v4.1.1**. The API and the `com.pd4ml.pdf.xfdf.cli.Pd4XfdfCli` command-line tool are part of the pd4ml library jar.
{% endhint %}

## What you can do with it

- **Export** every markup annotation and every non-signature form field value of a PDF to XFDF, from a `byte[]`, `File` or `InputStream`, with `XfdfExporter.export(...)`.
- **Import** an XFDF file into a PDF with `XfdfImporter.importInto(...)`: annotations are added as new PDF annotations; field values update fields that already exist in the PDF's `/AcroForm`. A field name that matches nothing is reported in `Result.getFieldsNotFound()`.
- **Update annotations in place** with `Options.updateIfExists(true)`: an annotation whose `name` (`/NM`) matches one already in the PDF is updated instead of added a second time.
- **Round-trip all XFDF annotation types**: `Text`, `Link`, `FreeText`, `Line`, `Square`, `Circle`, `Polygon`, `PolyLine`, `Highlight`, `Underline`, `Squiggly`, `StrikeOut`, `Stamp`, `Caret`, `Ink`, `Popup`, `FileAttachment`, `Sound` and `Redact`.
- **Filter** export or import with `Options.types(String)` (annotation types such as `square`, field types `Tx`/`Btn`/`Ch`) and `Options.ids(String)` (annotation `/NM` values, fully-qualified field names).
- **Read encrypted PDFs** with the user or owner password, and **optimize or encrypt the imported PDF** with `Options.optimizeOutput(true)` and `Options.encryptOutput(...)`.
- **Keep tagged PDFs tagged**: in a PDF that has a structure tree, each newly added annotation gets its own structure element.
- **Work with XFDF without a PDF**: `XfdfReader.read(byte[])` parses XFDF into a plain `XfdfDocument` model of `XfdfAnnotation` and `XfdfField` objects.

## Quick start

Export the annotations and field values of one PDF and import them into another (both methods throw `XfdfException`):

```java
import com.pd4ml.pdf.xfdf.XfdfExporter;
import com.pd4ml.pdf.xfdf.XfdfImporter;
import java.nio.file.Files;
import java.nio.file.Paths;

byte[] reviewed = Files.readAllBytes(Paths.get("reviewed.pdf"));
byte[] xfdf = XfdfExporter.export(reviewed);

byte[] original = Files.readAllBytes(Paths.get("original.pdf"));
XfdfImporter.Options options = new XfdfImporter.Options()
        .updateIfExists(true);
XfdfImporter.Result result = XfdfImporter.importInto(original, xfdf, options);
Files.write(Paths.get("annotated.pdf"), result.getPdf());

System.out.println(result.getAnnotationsAdded() + " added, "
        + result.getFieldsUpdated() + " field(s) updated");
```

The same from the command line:

```bash
java -cp pd4ml.jar com.pd4ml.pdf.xfdf.cli.Pd4XfdfCli export --in=reviewed.pdf --out=comments.xfdf
java -cp pd4ml.jar com.pd4ml.pdf.xfdf.cli.Pd4XfdfCli import --in=original.pdf --xfdf=comments.xfdf --out=annotated.pdf --update-if-exists
```

## When to use it

Use PD4ML PDF XFDF when the data you need to move is annotations or form field values. It does not create new form fields and does not regenerate appearance streams. PD4ML's HTML converter turns `<input>`, `<select>` and `<textarea>` elements into AcroForm fields, so XFDF can fill or read the fields of a PDF that PD4ML produced.

| Task | Tool |
|---|---|
| Export or import annotations and form field values | PD4ML PDF XFDF |
| Read, inspect or edit arbitrary PDF objects | [PD4ML PDF COS](pd4ml-pdf-cos) |
| Combine page ranges from several PDFs into one | [PD4ML PDF Merge](pd4ml-pdf-merge) |
| Make an existing PDF smaller | [PD4ML PDF Optimizer](pd4ml-pdf-optimizer) |
| Sign a PDF digitally | [PD4ML PDF Signing](pd4ml-pdf-signing) |

## In this section

- [PD4ML XFDF API - Programmer's Manual](pd4ml-pdf-xfdf/pd4ml-xfdf-manual) - architecture, the export and import API, annotation type coverage, form field rules, filtering, encryption, error messages and tagged PDFs.
- [Examples](pd4ml-pdf-xfdf/pd4ml-xfdf-examples) - eight runnable use-case classes in the `pd4ml-examples` repository, from a basic round trip to error handling.
- [pd4xfdfcli Reference](pd4ml-pdf-xfdf/pd4xfdfcli-reference) - `export` and `import` modes, all flags, exit codes and troubleshooting.
- [Javadoc](https://pd4ml.com/javadoc/com/pd4ml/pdf/xfdf/package-summary.html) - API reference for `com.pd4ml.pdf.xfdf`.