> For the complete documentation index, see [llms.txt](https://docs.pd4ml.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pd4ml.com/pd4ml-v3-to-v4-migration-guide.md).

# PD4ML v3 to v4 Migration Guide

PD4ML v4 is a substantial rewrite of the engine underneath a largely familiar API surface. Most call sites carry over with only a renamed method or a changed parameter type, but a handful of areas -- most notably the conversion flow itself, and the classes used for page geometry -- changed enough in shape that a mechanical find-and-replace won't get an existing v3 integration all the way to a working v4 build. This guide walks through what changed and why, section by section, and closes with a full method-by-method correspondence table for the rest. It complements the [PD4ML Programmer's Manual](/pd4ml-manual.md) (written against v4 throughout) and the [Usage Examples](/usage-examples.md) page (which shows v3 and v4 code side by side for the majority of common tasks).

## 1. Activation

Software activation is new in v4. Where v3 shipped without any license-file mechanism, v4 looks for a `pd4ml.lic` file -- containing an activation code obtained from the vendor's licensing page -- on the classpath or in the working directory, unless a code or a license-file URL is passed explicitly to the `PD4ML` constructor instead. The activation code encodes both the licensed feature set and the maintenance/upgrade window it's valid for. Until a valid license is installed, PD4ML runs in evaluation mode: fully functional, but with watermarked output. If activation isn't taking effect as expected, `pd4ml.setLogLevel(255)` produces verbose diagnostic output that typically pinpoints why (an expired maintenance window, a code that doesn't match the running version, a `pd4ml.lic` that isn't actually on the classpath, and so on).

Existing license codes and account details are managed from the [View My Licenses](https://pd4ml.com/view-my-licenses/) page.

## 2. New Conversion Flow

The single biggest structural change is that conversion is no longer one call. v3's `render(source, output)` parsed the source and produced output in a single step, called once per output artifact. v4 splits this into an explicit two-phase model: `readHTML(...)` parses the source exactly once, after which any number of `writePDF(...)`, `writeRTF(...)`, `writeDOCX(...)`, or `renderAsImages(...)` calls can serialize that same parsed document to different formats or destinations -- without re-parsing. This also means metadata about the parsed document (via `getLastRenderInfo(...)`) becomes available for inspection before -- or instead of -- writing any output at all.

{% tabs %}
{% tab title="PD4ML v4" %}

```java
PD4ML pd4ml = new PD4ML();
String html = "TEST<pd4ml:page.break><b>Hello, World!</b>";
ByteArrayInputStream bais = new ByteArrayInputStream(html.getBytes());

// phase 1: parse
pd4ml.readHTML(bais);

File pdf = File.createTempFile("result", ".pdf");
FileOutputStream fos = new FileOutputStream(pdf);

// phase 2: render -- can be called more than once, against different
// write*()/renderAsImages() methods, without re-parsing
pd4ml.writePDF(fos);
```

{% endtab %}

{% tab title="PD4ML v3" %}

```java
PD4ML pd4ml = new PD4ML();
String html = "TEST<b>Hello, World!</b>";
StringReader bais = new StringReader(html);

File pdf = File.createTempFile("result", ".pdf");
FileOutputStream fos = new FileOutputStream(pdf);

// a single call both parses the source and writes the output
pd4ml.render(bais, fos);
```

{% endtab %}
{% endtabs %}

## 3. PDF Document Defaults: Scale Factor, Margins, and View Mode

Three settings govern how source content maps onto the printed page, and their defaults changed between versions: `pageSize` defaults to A4 in both, `pageMargins` defaults to 10 mm on every side in v4 versus the more granular 50/25/25/25 pt (top/right/bottom/left) in v3, and `htmlWidth` (the virtual viewport width the source is laid out against before scaling) defaults to 640px in both. An `htmlWidth` of 727px is worth knowing about specifically: at that value, and only that value, PD4ML's internal scale factor works out to a 1:1 pixel-to-point correspondence at the PDF-standard 72 DPI -- convenient when reasoning about how a CSS pixel dimension will translate to printed size.

An integration that needs to reproduce v3's original defaults exactly under v4, rather than adopt the new ones, can do so explicitly:

```java
PD4ML pd4ml = new PD4ML();
pd4ml.setParam(Constants.PD4ML_DOCUMENT_VIEW_MODE, "OneColumn");
pd4ml.setHtmlWidth(640);
pd4ml.addStyle("BODY { margin: 8px }", true);
pd4ml.setPageSize(PageSize.A4);
pd4ml.setPageMargins(new PageMargins(50, 25, 25, 25, Units.PT));
```

## 4. Document Headers and Footers

v3 modeled a header or footer as a `PD4PageMark` object, whose `getHtmlTemplate(int pageNumber)` method was invoked once per page to compute that page's markup. v4 replaces this with a direct HTML string passed to `setPageHeader()`/`setPageFooter()`, with an optional scope parameter targeting a specific page range in place of per-page conditional logic in code -- and the same content can equally well be declared inline in the source HTML with the `<pd4ml:page.header>`/`<pd4ml:page.footer>` tags. All three forms support the `$[page]`, `$[total]`, and `$[title]` placeholders.

{% tabs %}
{% tab title="PD4ML v4 (API)" %}

```java
pd4ml.setPageHeader("$[title]", 30, "1");
pd4ml.setPageFooter("Total pages: $[total]", 30, "1");

pd4ml.setPageHeader("<b>$[title]</b> $[page]/$[total]", 30, "2+");
pd4ml.setPageFooter("<div style='width: 100%; text-align: right'>Page: $[page]</div>", 30, "2+");
```

{% endtab %}

{% tab title="PD4ML v4 (inline tags)" %}

```html
<html>
<head>
<title>Header/Footer example</title>
<style>BODY {font-family: Arial}</style>
</head>
<body>

<pd4ml:page.header height=30>$[title]</pd4ml:page.header>
<pd4ml:page.footer height=30>Total pages: $[total]</pd4ml:page.footer>

First Page

<pd4ml:page.break>

<pd4ml:page.header height=30><b>$[title]</b> $[page]/$[total]</pd4ml:page.header>
<pd4ml:page.footer height=30><div style='width: 100%; text-align: right'>Page: $[page]</div></pd4ml:page.footer>

Second Page
</body>
</html>
```

{% endtab %}

{% tab title="PD4ML v3" %}

```java
PD4PageMark header = new PD4PageMark() {
    public String getHtmlTemplate(int pageNumber) {
        if (pageNumber == 1) {
            return "<html><body>$[title]";
        } else {
            return "<html><body><b>$[title]</b> $[page]/$[total]";
        }
    }
};
PD4PageMark footer = new PD4PageMark() {
    public String getHtmlTemplate(int pageNumber) {
        if (pageNumber == 1) {
            return "<html><body>Total pages: $[total]";
        } else {
            return "<html><body><div style='width: 100%; text-align: right'>Page: $[page]</div>";
        }
    }
};
header.setAreaHeight(30);
footer.setAreaHeight(30);

pd4ml.setPageHeader(header);
pd4ml.setPageFooter(footer);
```

{% endtab %}
{% endtabs %}

See also the [Programmer's Manual's JSP taglib section](https://pd4ml.com/support-topics/pd4ml-v4-programmers-manual/#pd4ml-jsp-taglib-and-web-applications) for the same placeholders used from a JSP page.

## 5. JSP Taglib

The JSP taglib now ships as an integral part of the main library rather than a separate artifact. The recommended custom-tag prefix also changed, from `pd4ml:` to `pd4tl:` -- freeing `pd4ml:` to unambiguously refer only to PD4ML's own proprietary tags (`<pd4ml:page.break>` and the like) within the same page, rather than being shared between the taglib's own directives and PD4ML's markup extensions.

```jsp
<%@ taglib uri="https://pd4ml.com/tlds/4.0" prefix="pd4tl"%>
<%@page contentType="text/html; charset=ISO8859_1"%>
<pd4tl:transform
  screenWidth="400"
  pageFormat="A5"
  pageOrientation="landscape"
  pageInsets="100,100,100,100,points">
<html>
<head>
<title>pd4ml test</title>
<style type="text/css">
body {
	color: red;
	font-family: Tahoma, "Sans-Serif";
	font-size: 10pt;
}
</style>
</head>
<body>
	<p>Hello, World!</p>
	<pd4ml:page.break />
	<table style="border: 1px solid gray; border-radius: 5px; background-color: #f8f8f8; color: #000000">
		<tr>
			<td>Hello, New Page!</td>
		</tr>
	</table>
</body>
</html>
</pd4tl:transform>
```

## 6. Full API Correspondence Table

The table below maps every v3 `PD4ML` method referenced in the vendor's migration notes to its v4 successor, linking each to its respective Javadoc (v3's now-archived Javadoc at `old.pd4ml.com`, and v4's current one). Where a v3 method has no listed v4 successor, that most often means its functionality was folded into a more general mechanism described elsewhere in this guide, or the behavior it controlled is now automatic; treat those as "no longer applicable" rather than "still there under a different name."

| v3 method                                                                                                                                                                                                                                                                               | v4 method                                                                                                                                                                                                                                                                                                                                                                                                                                      | What changed                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`addDocumentActionHandler(String, String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#addDocumentActionHandler\(java.lang.String,%20java.lang.String\))                                                                                                                     | [`addDocumentActionHandler(String, String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#addDocumentActionHandler-java.lang.String-java.lang.String-)                                                                                                                                                                                                                                                                                       | Unchanged                                                                                                                                                                                                                                                                                   |
| [`addMetadata(String, String, boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#addMetadata\(java.lang.String,%20java.lang.String,%20boolean\))                                                                                                                           | [`addMetadata(String, String, boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#addMetadata-java.lang.String-java.lang.String-boolean-)                                                                                                                                                                                                                                                                                                | Unchanged                                                                                                                                                                                                                                                                                   |
| [`addStyle(String, boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#addStyle\(java.lang.String,%20boolean\))                                                                                                                                                             | [`addStyle(String, boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#addStyle-java.lang.String-boolean-)                                                                                                                                                                                                                                                                                                                               | Unchanged                                                                                                                                                                                                                                                                                   |
| [`addStyle(URL, boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#addStyle\(URL,%20boolean\))                                                                                                                                                                             | [`addStyle(URL, boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#addStyle-java.net.URL-boolean-)                                                                                                                                                                                                                                                                                                                                      | Unchanged                                                                                                                                                                                                                                                                                   |
| [`adjustHtmlWidth()`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#adjustHtmlWidth\(\))                                                                                                                                                                                         | [`adjustHtmlWidth(boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#adjustHtmlWidth-boolean-)                                                                                                                                                                                                                                                                                                                                          | Now takes an explicit boolean instead of being an always-on toggle call                                                                                                                                                                                                                     |
| [`changePageOrientation(Dimension)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#changePageOrientation\(Dimension\))                                                                                                                                                           | [`PageSize.rotate()`](https://pd4ml.com/javadoc/com/pd4ml/PageSize.html#rotate--)                                                                                                                                                                                                                                                                                                                                                              | Moved from a `PD4ML` instance method to a method on `PageSize` itself                                                                                                                                                                                                                       |
| [`clearCache()`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#clearCache\(\))                                                                                                                                                                                                   | [`terminate()`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#terminate--)                                                                                                                                                                                                                                                                                                                                                                    | Renamed                                                                                                                                                                                                                                                                                     |
| [`disableHyperlinks()`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#disableHyperlinks\(\))                                                                                                                                                                                     | [`enableHyperlinks(boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#enableHyperlinks-boolean-)                                                                                                                                                                                                                                                                                                                                        | Inverted: call `enableHyperlinks(false)`                                                                                                                                                                                                                                                    |
| [`enableDebugInfo()`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#enableDebugInfo\(\))                                                                                                                                                                                         | [`setLogLevel(int)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setLogLevel-int-)                                                                                                                                                                                                                                                                                                                                                          | Replaced by a graduated log level; use `setLogLevel(255)` for maximum verbosity                                                                                                                                                                                                             |
| [`enableImgSplit(boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#enableImgSplit\(boolean\))                                                                                                                                                                             | [`addStyle(String, boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#addStyle-java.lang.String-boolean-)                                                                                                                                                                                                                                                                                                                               | Superseded by ordinary CSS page-break control passed through `addStyle()` rather than a dedicated flag                                                                                                                                                                                      |
| `enableRenderingPatch(boolean)`                                                                                                                                                                                                                                                         | --                                                                                                                                                                                                                                                                                                                                                                                                                                             | No v4 successor listed                                                                                                                                                                                                                                                                      |
| `enableSmartTableBreaks(boolean)`                                                                                                                                                                                                                                                       | --                                                                                                                                                                                                                                                                                                                                                                                                                                             | No v4 successor listed                                                                                                                                                                                                                                                                      |
| `enableTableBreaks(boolean)`                                                                                                                                                                                                                                                            | --                                                                                                                                                                                                                                                                                                                                                                                                                                             | No v4 successor listed                                                                                                                                                                                                                                                                      |
| [`fitPageVertically()`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#fitPageVertically\(\))                                                                                                                                                                                     | [`fitPageVertically(int)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#fitPageVertically-int-)                                                                                                                                                                                                                                                                                                                                              | Now takes an explicit alignment constant                                                                                                                                                                                                                                                    |
| [`generateMulticolumn(int, int, boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#generateMulticolumn\(int,%20int,%20boolean\))                                                                                                                                           | [`generateMulticolumn(int, int, boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#generateMulticolumn-int-int-boolean-)                                                                                                                                                                                                                                                                                                                | Unchanged                                                                                                                                                                                                                                                                                   |
| [`generateOutlines(boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#generateOutlines\(boolean\))                                                                                                                                                                         | [`generateBookmarksFromHeadings(boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#generateBookmarksFromHeadings-boolean-) / [`generateBookmarksFromAnchors(boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#generateBookmarksFromAnchors-boolean-)                                                                                                                                                                            | Split into two purpose-specific methods (see the [Usage Examples' Create Bookmarks entry](/usage-examples.md))                                                                                                                                                                              |
| [`generatePdfa(boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#generatePdfa\(boolean\))                                                                                                                                                                                 | [`writePDF(OutputStream, String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#writePDF-java.io.OutputStream-java.lang.String-) with [`Constants.PDFA`](https://pd4ml.com/javadoc/com/pd4ml/Constants.html#PDFA)                                                                                                                                                                                                                            | Folded into the write call itself rather than a standalone flag set beforehand                                                                                                                                                                                                              |
| [`generatePdfForms(boolean, String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#generatePdfForms\(boolean,%20java.lang.String\))                                                                                                                                             | [`generateForms(boolean, String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#generateForms-boolean-java.lang.String-)                                                                                                                                                                                                                                                                                                                     | Renamed                                                                                                                                                                                                                                                                                     |
| [`getCache()`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#getCache\(\))                                                                                                                                                                                                       | [`getCache()`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#getCache--)                                                                                                                                                                                                                                                                                                                                                                      | Unchanged                                                                                                                                                                                                                                                                                   |
| [`getLastRenderInfo(String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#getLastRenderInfo\(java.lang.String\))                                                                                                                                                               | [`getLastRenderInfo(String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#getLastRenderInfo-java.lang.String-)                                                                                                                                                                                                                                                                                                                              | Unchanged                                                                                                                                                                                                                                                                                   |
| [`getVersion()`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#getVersion\(\))                                                                                                                                                                                                   | [`getVersion()`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#getVersion--)                                                                                                                                                                                                                                                                                                                                                                  | Unchanged                                                                                                                                                                                                                                                                                   |
| `interpolateImages(boolean)`                                                                                                                                                                                                                                                            | --                                                                                                                                                                                                                                                                                                                                                                                                                                             | No v4 successor listed (image interpolation is presumably automatic now)                                                                                                                                                                                                                    |
| [`isDemoMode()`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#isDemoMode\(\))                                                                                                                                                                                                   | [`isDemoMode()`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#isDemoMode--)                                                                                                                                                                                                                                                                                                                                                                  | Unchanged                                                                                                                                                                                                                                                                                   |
| [`isPro()`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#isPro\(\))                                                                                                                                                                                                             | [`isPro()`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#isPro--)                                                                                                                                                                                                                                                                                                                                                                            | Unchanged                                                                                                                                                                                                                                                                                   |
| [`merge(InputStream, int, int, boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#merge\(InputStream,%20int,%20int,%20boolean\)) / [`merge(Reader, int, int, boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#merge\(Reader,%20int,%20int,%20boolean\))     | [`merge(PdfDocument, int, int, boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#merge-com.pd4ml.PdfDocument-int-int-boolean-)                                                                                                                                                                                                                                                                                                         | Both v3 overloads consolidate onto one v4 overload taking a `PdfDocument`                                                                                                                                                                                                                   |
| [`monitorProgress(PD4ProgressListener)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#monitorProgress\(org.zefer.pd4ml.PD4ProgressListener\))                                                                                                                                   | [`monitorProgressWith(ProgressListener)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#monitorProgressWith-com.pd4ml.ProgressListener-)                                                                                                                                                                                                                                                                                                      | Renamed -- **but see the caveat immediately below the table**                                                                                                                                                                                                                               |
| [`outputFormat(String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#outputFormat\(java.lang.String\)) / [`outputFormat(String, int, int)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#outputFormat\(java.lang.String,%20int,%20int\))                               | [`writePDF(...)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#writePDF-java.io.OutputStream-) / [`writeRTF(...)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#writeRTF-java.io.OutputStream-boolean-) / [`renderAsImages()`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#renderAsImages--)                                                                                                                                            | The v3 "set a format flag, then render" model is replaced by calling the write method for the desired format directly                                                                                                                                                                       |
| [`outputRange(String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#outputRange\(java.lang.String\))                                                                                                                                                                           | [`outputRange(String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#outputRange-java.lang.String-)                                                                                                                                                                                                                                                                                                                                          | Unchanged                                                                                                                                                                                                                                                                                   |
| [`overrideDocumentEncoding(String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#overrideDocumentEncoding\(java.lang.String\))                                                                                                                                                 | [`overrideDocumentEncoding(String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#overrideDocumentEncoding-java.lang.String-)                                                                                                                                                                                                                                                                                                                | Unchanged                                                                                                                                                                                                                                                                                   |
| [`predictPageHeight(Insets, Dimension, int)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#predictPageHeight\(Insets,%20Dimension,%20int\))                                                                                                                                     | [`predictPageHeight(PageMargins, PageSize, int)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#predictPageHeight-com.pd4ml.PageMargins-com.pd4ml.PageSize-int-)                                                                                                                                                                                                                                                                              | Same purpose; parameter types updated to `PageMargins`/`PageSize`                                                                                                                                                                                                                           |
| [`predictScale(Insets, Dimension, int)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#predictScale\(Insets,%20Dimension,%20int\))                                                                                                                                               | [`predictScale(PageMargins, PageSize, int)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#predictScale-com.pd4ml.PageMargins-com.pd4ml.PageSize-int-)                                                                                                                                                                                                                                                                                        | Same purpose; parameter types updated to `PageMargins`/`PageSize`                                                                                                                                                                                                                           |
| [`protectPhysicalUnitDimensions()`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#protectPhysicalUnitDimensions\(\))                                                                                                                                                             | [`protectPhysicalUnitDimensions(boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#protectPhysicalUnitDimensions-boolean-)                                                                                                                                                                                                                                                                                                              | Now takes an explicit boolean instead of being an always-on toggle call                                                                                                                                                                                                                     |
| [`render(InputStreamReader, OutputStream[, URL])`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#render\(InputStreamReader,%20OutputStream\))                                                                                                                                    | [`readHTML(InputStream[, URL])`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#readHTML-java.io.InputStream-) + [`writePDF(OutputStream)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#writePDF-java.io.OutputStream-)                                                                                                                                                                                                                     | Splits into the two-phase model (§2)                                                                                                                                                                                                                                                        |
| [`render(String, OutputStream)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#render\(java.lang.String,%20OutputStream\)) / [`render(URL, OutputStream)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#render\(URL,%20OutputStream\))                                   | [`readHTML(URL)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#readHTML-java.net.URL-) + `writePDF(OutputStream)`                                                                                                                                                                                                                                                                                                                            | Splits into the two-phase model, source addressed as a URL                                                                                                                                                                                                                                  |
| [`render(StringReader, OutputStream[, URL[, String]])`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#render\(StringReader,%20OutputStream\))                                                                                                                                    | [`readHTML(InputStream, URL[, String])`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#readHTML-java.io.InputStream-java.net.URL-java.lang.String-) + `writePDF(OutputStream)`                                                                                                                                                                                                                                                                | Splits into the two-phase model, with an optional explicit source encoding                                                                                                                                                                                                                  |
| [`render(StringReader[], OutputStream, URL)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#render\(StringReader%5B%5D,%20OutputStream,%20URL\)) / [`render(URL[], OutputStream)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#render\(URL%5B%5D,%20OutputStream\))     | `readHTML(...)` + `writePDF(...)` per source, combined with [`PdfDocument.mergePDFs(InputStream, InputStream, OutputStream)`](https://pd4ml.com/javadoc/com/pd4ml/PdfDocument.html#mergePDFs-java.io.InputStream-java.io.InputStream-java.io.OutputStream-)                                                                                                                                                                                    | v3's "render several sources and merge them" array overloads are replaced by converting each source individually and merging the resulting PDFs explicitly                                                                                                                                  |
| [`renderAsImages(StringReader, URL, int, int)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#renderAsImages\(StringReader,%20URL,%20int,%20int\)) / [`renderAsImages(URL, int, int)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#renderAsImages\(URL,%20int,%20int\)) | `readHTML(...)` + one of [`renderAsImages()`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#renderAsImages--) / [`renderAsImages(File, String, String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#renderAsImages-java.io.File-java.lang.String-java.lang.String-) / [`renderAsImages(String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#renderAsImages-java.lang.String-)                                                         | Splits into the two-phase model, with a choice of in-memory, to-disk, or encoded-bytes image output                                                                                                                                                                                         |
| `resetAddedStyles()`                                                                                                                                                                                                                                                                    | --                                                                                                                                                                                                                                                                                                                                                                                                                                             | No v4 successor listed                                                                                                                                                                                                                                                                      |
| [`setAuthorName(String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setAuthorName\(java.lang.String\))                                                                                                                                                                       | [`setAuthorName(String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setAuthorName-java.lang.String-)                                                                                                                                                                                                                                                                                                                                      | Unchanged                                                                                                                                                                                                                                                                                   |
| [`setCache(PD4Cache)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setCache\(org.zefer.pd4ml.PD4Cache\))                                                                                                                                                                       | [`setCache(Object)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setCache-java.lang.Object-)                                                                                                                                                                                                                                                                                                                                                | Same purpose; parameter type loosened to `Object`                                                                                                                                                                                                                                           |
| [`setCookie(String, String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setCookie\(java.lang.String,%20java.lang.String\))                                                                                                                                                   | [`setCookie(String, String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setCookie-java.lang.String-java.lang.String-)                                                                                                                                                                                                                                                                                                                     | Unchanged                                                                                                                                                                                                                                                                                   |
| [`setDefaultTTFs(String, String, String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setDefaultTTFs\(java.lang.String,%20java.lang.String,%20java.lang.String\))                                                                                                             | [`addStyle(String, boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#addStyle-java.lang.String-boolean-)                                                                                                                                                                                                                                                                                                                               | Superseded by an ordinary CSS `@font-face` rule passed to `addStyle()` (see the [Usage Examples' Add Style Programmatically entry](/usage-examples.md))                                                                                                                                     |
| [`setDocumentTitle(String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setDocumentTitle\(java.lang.String\))                                                                                                                                                                 | [`setDocumentTitle(String)`](https://pd4ml.tech/javadoc/com/pd4ml/PD4ML.html#setDocumentTitle-java.lang.String-)                                                                                                                                                                                                                                                                                                                               | Unchanged                                                                                                                                                                                                                                                                                   |
| [`setDynamicParams(Map)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setDynamicParams\(java.util.Map\))                                                                                                                                                                       | [`setDynamicData(Map)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setDynamicData-java.util.Map-) / [`setParam(String, String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setParam-java.lang.String-java.lang.String-) / [`setRenderingHints(Map)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setRenderingHints-java.util.Map-)                                                                                                 | v3's single, catch-all method splits into three narrower ones -- placeholder substitution values, individual named parameters, and rendering hints, respectively. **See the caveat below the table**, though: at least one other official example still calls `setDynamicParams()` under v4 |
| [`setHtmlWidth(int)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setHtmlWidth\(int\))                                                                                                                                                                                         | [`setHtmlWidth(int)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setHtmlWidth-int-)                                                                                                                                                                                                                                                                                                                                                        | Unchanged                                                                                                                                                                                                                                                                                   |
| [`setPageHeader(PD4PageMark)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setPageHeader\(org.zefer.pd4ml.PD4PageMark\)) / [`setPageFooter(PD4PageMark)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setPageFooter\(org.zefer.pd4ml.PD4PageMark\))                   | [`setPageHeader(String, int[, String])`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setPageHeader-java.lang.String-int-) / [`setPageFooter(String, int[, String])`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setPageFooter-java.lang.String-int-)                                                                                                                                                                                    | Replaced the callback object with a direct HTML string plus scope (§4)                                                                                                                                                                                                                      |
| [`setPageInsets(Insets)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setPageInsets\(Insets\)) / [`setPageInsetsMM(Insets)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setPageInsetsMM\(Insets\))                                                                   | [`setPageMargins(PageMargins[, String])`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setPageMargins-com.pd4ml.PageMargins-)                                                                                                                                                                                                                                                                                                                | The separate points/millimeters methods collapse into one call; units are now chosen via the `PageMargins` constructor instead of which method you call                                                                                                                                     |
| [`setPageSize(Dimension)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setPageSize\(Dimension\)) / [`setPageSizeMM(Dimension)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setPageSizeMM\(Dimension\))                                                               | [`setPageSize(PageSize[, String])`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setPageSize-com.pd4ml.PageSize-)                                                                                                                                                                                                                                                                                                                            | Same collapse as `setPageMargins`, for page size instead of margins                                                                                                                                                                                                                         |
| [`setPermissions(String, int, boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setPermissions\(java.lang.String,%20int,%20boolean\))                                                                                                                                     | [`setPermissions(String, int)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setPermissions-java.lang.String-int-)                                                                                                                                                                                                                                                                                                                           | Trailing legacy-mode boolean dropped (see the [Usage Examples' Set Document Password entry](/usage-examples.md))                                                                                                                                                                            |
| [`setSessionID(String)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#setSessionID\(java.lang.String\))                                                                                                                                                                         | [`setSessionID(String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#setSessionID-java.lang.String-)                                                                                                                                                                                                                                                                                                                                        | Unchanged                                                                                                                                                                                                                                                                                   |
| [`translate(int)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#translate\(int\))                                                                                                                                                                                               | [`translateToPt(float)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#translateToPt-float-)                                                                                                                                                                                                                                                                                                                                                  | Renamed, and now takes/returns a `float` rather than an `int`                                                                                                                                                                                                                               |
| `useAdobeFontMetrics(boolean)`                                                                                                                                                                                                                                                          | --                                                                                                                                                                                                                                                                                                                                                                                                                                             | No v4 successor listed                                                                                                                                                                                                                                                                      |
| [`useHttpRequest(HttpServletRequest, HttpServletResponse)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#useHttpRequest\(HttpServletRequest,%20HttpServletResponse\))                                                                                                           | [`useHttpRequest(HttpServletRequest, HttpServletResponse)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#useHttpRequest-javax.servlet.http.HttpServletRequest-javax.servlet.http.HttpServletResponse-)                                                                                                                                                                                                                                       | Unchanged                                                                                                                                                                                                                                                                                   |
| [`useServletContext(ServletContext)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#useServletContext\(ServletContext\))                                                                                                                                                         | [`useHttpRequest(...)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#useHttpRequest-javax.servlet.http.HttpServletRequest-javax.servlet.http.HttpServletResponse-)                                                                                                                                                                                                                                                                           | Folded into `useHttpRequest()`                                                                                                                                                                                                                                                              |
| [`useTTF(String, boolean)`](https://old.pd4ml.com/api/org/zefer/pd4ml/PD4ML.html#useTTF\(java.lang.String,%20boolean\))                                                                                                                                                                 | [`useTTF(String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#useTTF-java.lang.String-) / [`useTTF(String, boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#useTTF-java.lang.String-boolean-) / [`useTTF(String, String)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#useTTF-java.lang.String-java.lang.String-) + [`embedTTFs(boolean, boolean)`](https://pd4ml.com/javadoc/com/pd4ml/PD4ML.html#embedTTFs-boolean-boolean-) | The single v3 overload expands into three v4 overloads for different addressing needs, with glyph-embedding behavior configured separately via `embedTTFs()` (see the [Usage Examples' i18n section](/usage-examples.md))                                                                   |

{% hint style="warning" %}
**Two entries in this table conflict with tested example code published elsewhere on pd4ml.com**, and are worth double-checking against the actual Javadoc for the PD4ML build in use before relying on them:

* **`monitorProgress`/`monitorProgressWith`** -- this migration guide lists v3 as `monitorProgress(PD4ProgressListener)` and v4 as `monitorProgressWith(ProgressListener)`. The [Usage Examples' Add Progress Listener entry](/usage-examples.md), however, shows the *opposite* pairing in its tested v3/v4 code samples: v3 calling `monitorProgressWith(ProgressListener)` and v4 calling `monitorProgress(PD4ProgressListener)`.
* **`setDynamicParams`** -- this migration guide lists it as v3-only, superseded in v4 by `setDynamicData`/`setParam`/`setRenderingHints`. The [Usage Examples' Add Custom Resource Loader entry](/usage-examples.md), however, calls `pd4ml.setDynamicParams(map)` directly in its v4 code sample.

Both discrepancies come from pd4ml.com's own published documentation rather than from anything in this rewrite -- they're surfaced here rather than silently resolved one way or the other.
{% endhint %}

## See also

* [PD4ML Programmer's Manual](/pd4ml-manual.md) -- the current (v4) API, described from scratch rather than as a diff against v3.
* [Usage Examples](/usage-examples.md) -- runnable examples with v3 and v4 code shown side by side for most common tasks.
* [Support Forums](https://pd4ml.com/forums/) and [Extended Support Plans](https://pd4ml.com/pd4ml-extended-support-plans/) -- for migration questions not covered here.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pd4ml.com/pd4ml-v3-to-v4-migration-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.