Java と PDFtk による PDF フォーム入力の自動化
Java のマップから既存の PDF フォームに値を入力し、フィールドを編集可能なまま残すか、ページの内容に変換するかを選択します。以下の例では、Java の XML API で XFDF を生成し、PDFtk Java を実行して新しい PDF を保存します。既存の出力先は上書きしません。
PDFtk の fill_form 操作は、既存の AcroForm フィールドに対して FDF または XFDF を受け付けます。スキャンしたページにフィールドを作成する機能ではありません。この手順では、信頼できる、暗号化されていない AcroForm テンプレートを使用してください。XFA フォームと署名済み PDF には別のワークフローが必要です。
前提条件
- 保守が継続されている JDK。
javaとjavacがPATH上にあること - Linux と、JDK とは別にインストールした Bash、
curl、GNUsha256sum - フィールド名が判明しており、入力する文字に対応したフォントを備えた既存の AcroForm テンプレート
- ハードリンクをサポートするファイルシステム上の、書き込み可能な作業ディレクトリ
動作を検証した実行環境は、Linux 上の OpenJDK 21.0.12.1 と PDFtk Java 3.3.3 です。これらはテスト済みのバージョンであり、Java 自体の最低要件ではありません。Temurin 21.0.12.1など、保守が継続されている JDK 21 リリースを、アーカイブからのインストールガイドに従って使用してください。以下のインストールコマンドは Linux 向けです。macOS と Windows のセットアップは対象外です。
Java 環境での PDFtk のセットアップ
PDFtk Java は PDFtk の Java 移植版です。バージョン別のインストールガイドでは、依存関係を含む単体の JAR を提供しています。この JAR を新しい作業ディレクトリにダウンロードすると、システムのインストールを変更せずに、プログラムで使用する PDFtk のバージョンを確定できます。
ファイルを作成する前に、別途必要なコマンドラインツールを確認します。書き込み可能な親ディレクトリで、次のブロックを Bash に貼り付けてください。成功すると、シェルの現在のディレクトリが pdf-form-work になります。
java -version && javac -version &&
command -v curl && command -v sha256sum &&
mkdir pdf-form-work && cd pdf-form-work
ディレクトリがすでに存在する場合、このブロックは停止します。内容を保持して別の名前を選ぶか、以前作成したディレクトリに移動して、途中のセットアップを再開してください。pdf-form-work 内で、JAR をダウンロードして検証します。
curl -fsSLo pdftk-java-3.3.3-all.jar \
https://gitlab.com/api/v4/projects/5024297/packages/generic/pdftk-java/v3.3.3/pdftk-all.jar &&
printf '%s %s\n' \
a694d49bd03e1edd4c23b3ba808bc221eb8a8ccfe7bfd2a0a884b2b2fb425188 \
pdftk-java-3.3.3-all.jar | sha256sum -c - &&
java -jar pdftk-java-3.3.3-all.jar --version
このチェックサムは、公開元のパッケージメタデータと一致します。バージョンの出力に pdftk port to java 3.3.3 が含まれることを確認してください。ダウンロードまたは検証に失敗した場合は、自分が所有する同じディレクトリで、ダウンロード用ブロックを再実行してください。置き換えられるのはダウンロードした JAR のみです。検証に失敗したまま先に進まないでください。以降のコマンドはすべて pdf-form-work から実行します。
PDFtk による PDF フォームのフィールド情報の抽出
テンプレートをこのディレクトリに template.pdf として配置します。フィールド名とエクスポート値を UTF-8 で確認します。
java -jar pdftk-java-3.3.3-all.jar template.pdf dump_data_fields_utf8
テキストフィールドには、たとえば Name のような名前があります。チェックボックスとラジオボタンのフィールドでは、FieldStateOption の値も報告されます。表示ラベルや、推測した Yes の値ではなく、報告された名前と値を正確に使用してください。マップを記述する前に、使用する名前を記録します。PDFtk コマンドが正常終了しても、不明なフィールドには値が入力されないことがあります。
Java によるフォーム入力の自動化
次の完全なサンプルを PdfFormFiller.java として保存します。fillForm は、フィールド名と値のマップを受け取ります。CLI の例では Name と Date を渡しています。これらのキーを、確認したテンプレートに合わせて変更してください。プログラムの実行時には、JAR を作業ディレクトリに置いておく必要があります。
import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.transform.OutputKeys;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
public class PdfFormFiller {
public static void fillForm(Path template, Path output, Map<String, String> values,
boolean flatten) throws Exception {
template = template.toAbsolutePath().normalize();
output = output.toAbsolutePath().normalize();
Path toolkit = Path.of("pdftk-java-3.3.3-all.jar").toAbsolutePath().normalize();
if (!Files.isRegularFile(toolkit)) {
throw new IOException("PDFtk Java JAR must be in the working directory");
}
if (!Files.isRegularFile(template)) {
throw new IOException("Template must be a regular file");
}
if (Files.exists(output, LinkOption.NOFOLLOW_LINKS)) {
throw new IOException("Output must not exist");
}
if (values.isEmpty() || values.entrySet().stream().anyMatch(
entry -> entry.getKey() == null || entry.getValue() == null)) {
throw new IllegalArgumentException("Supply nonnull field names and values");
}
Path temporary = Files.createTempDirectory(output.getParent(), ".pdf-form-");
Path data = temporary.resolve("data.xfdf");
Path candidate = temporary.resolve("result.pdf");
try {
writeXfdf(data, values);
List<String> arguments = new ArrayList<>(List.of("java", "-jar", toolkit.toString(),
template.toString(),
"fill_form", data.toString(), "output", candidate.toString()));
if (flatten) arguments.add("flatten");
arguments.add("dont_ask");
Process process = new ProcessBuilder(arguments)
.redirectOutput(ProcessBuilder.Redirect.DISCARD)
.redirectError(ProcessBuilder.Redirect.DISCARD).start();
process.getOutputStream().close();
try {
if (!process.waitFor(120, TimeUnit.SECONDS)) {
throw new IOException("PDFtk conversion timed out");
}
if (process.exitValue() != 0) {
throw new IOException("PDFtk conversion failed");
}
} finally {
if (process.isAlive()) {
process.destroyForcibly();
process.waitFor();
}
}
if (!Files.isRegularFile(candidate) || Files.size(candidate) == 0) {
throw new IOException("PDFtk did not produce a nonempty result");
}
// Same-filesystem publication fails if a destination appeared during conversion.
Files.createLink(output, candidate);
} finally {
Files.deleteIfExists(candidate);
Files.deleteIfExists(data);
Files.deleteIfExists(temporary);
}
}
private static void writeXfdf(Path path, Map<String, String> values) throws Exception {
String namespace = "http://ns.adobe.com/xfdf/";
Document document = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();
Element root = document.createElementNS(namespace, "xfdf");
document.appendChild(root);
Element fields = document.createElementNS(namespace, "fields");
root.appendChild(fields);
for (Map.Entry<String, String> entry : values.entrySet()) {
Element field = document.createElementNS(namespace, "field");
field.setAttribute("name", entry.getKey());
Element value = document.createElementNS(namespace, "value");
value.setTextContent(entry.getValue());
field.appendChild(value);
fields.appendChild(field);
}
var transformer = TransformerFactory.newInstance().newTransformer();
transformer.setOutputProperty(OutputKeys.ENCODING, "UTF-8");
try (OutputStream stream = Files.newOutputStream(path)) {
transformer.transform(new DOMSource(document), new StreamResult(stream));
}
}
public static void main(String[] args) {
if (args.length != 2) {
System.err.println("Usage: java -cp . PdfFormFiller <template.pdf> <new-output.pdf>");
System.exit(1);
}
try {
fillForm(Path.of(args[0]), Path.of(args[1]),
Map.of("Name", "Jane Doe", "Date", "2026-09-15"), true);
System.out.println("Filled PDF saved");
} catch (InterruptedException error) {
Thread.currentThread().interrupt();
System.err.println("PDF form filling interrupted");
System.exit(1);
} catch (Exception error) {
System.err.println("PDF form filling failed; check template, fields, destination, and PDFtk");
System.exit(1);
}
}
}
ソース、JAR、テンプレートがあるディレクトリでコンパイルして実行します。&& により、コンパイルに失敗した場合に、以前のビルドで残ったクラスが実行されるのを防ぎます。クラスパスを明示しているため、この例を含むプロジェクトで
CLASSPATH が設定されていても、この例が選択されます。
javac -encoding UTF-8 -cp . PdfFormFiller.java &&
java -cp . PdfFormFiller template.pdf filled_form.pdf
成功すると、プログラムは Filled PDF saved を表示し、filled_form.pdf を作成します。例の Name と Date フィールドを持つテンプレートでは、それぞれの位置に Jane Doe と 2026-09-15 が表示されます。同じコマンドを再実行すると、その出力先への書き込みは拒否され、既存のバイト列は変更されません。別のレコードには、新しい出力ファイル名を指定してください。
一時ディレクトリには XFDF の値と、出力候補の PDF が含まれます。この作業ディレクトリは、データに適した権限で保存してください。出力先への確定には Files.createLinkを使用し、変換中に作成された出力先への書き込みを拒否します。この処理にはハードリンクのサポートが必要で、PDF の暗号化は行いません。finally ブロックは通常の実行時にステージングファイルを削除しますが、JVM が強制終了されるとファイルが残ることがあります。
編集可能な出力とフラット化した出力の選択
例の fillForm 呼び出しの最後の引数 true は、PDFtk の flatten オプションを追加し、フィールドの外観をページの一部にします。フィールドを編集可能なまま残すには、この引数を false に変更して再コンパイルし、新しい出力先に書き込みます。
javac -encoding UTF-8 -cp . PdfFormFiller.java &&
java -cp . PdfFormFiller template.pdf editable_form.pdf
フラット化は、アクセス制御や改ざん防止の機能ではありません。
検証済みのテンプレートごとに、新しいマップを使って fillForm を呼び出します。たとえばチェックボックスには、真偽値を表す文字列ではなく、Accepted など、報告されたエクスポート値を使用します。複数行フィールドの値には改行を含められます。テンプレートの確認中はテスト用の架空のレコードをコードに保持し、実際のデータはソースファイルに埋め込まず、アプリケーションから渡してください。
値と外観の検証
filled_form.pdf を開き、表示される各フィールドの値と位置を意図したものと比較します。プログラムが確認するのは、プロセスの終了状態と、空でない出力ファイルの存在です。すべてのフィールドに正しく入力されたことまでは証明できません。新しいテンプレートのフラット化を確定する前に、編集可能な状態の結果を確認してください。
編集可能な出力では、保存された値も確認します。
java -jar pdftk-java-3.3.3-all.jar editable_form.pdf dump_data_fields_utf8
FieldValue をマップと照合してください。フラット化した PDF には、確認できる対話型フィールドが残っていません。そのため、このコマンドでページの表示内容の確認を代替することはできません。
- チェックボックスとラジオボタンの値は、テンプレートのエクスポート値と一致する必要があります。
- 選択フィールドでは、表示ラベルと保存された値が異なる場合があるため、両方を確認してください。
- このマップを使った例では、各フィールドにプレーンテキストの値を一つ書き込みます。リッチテキストや選択項目のリストは書き込みません。
- UTF-8 と XML のエスケープにより
Zoë & <Ada>などのテキストは保持されますが、テンプレートのフォントにも対応するグリフが必要です。保存された値が正しくても、長いテキストはフィールドの境界で切れる場合があります。
よくある問題のトラブルシューティング
PDFtk が起動しない
Java プログラムと同じ作業ディレクトリから JAR のバージョン確認コマンドを実行してください。検証済みの JAR がそこにあり、java が引き続き
PATH 上にあることを確認します。プログラムは JAR を直接起動するため、pdftk のシェルエイリアスは不要です。
権限の問題
プロセスには、テンプレートの読み取り権限と出力先ディレクトリへの書き込み権限が必要です。そのファイルシステムでハードリンクがサポートされていることも必要です。出力先への確定に失敗した場合、上書きコピーに切り替えないでください。対応するストレージを選ぶか、上書きしないことを明示的に保証する代替手段を実装してください。
暗号化された PDF の扱い
暗号化されたテンプレートには、別途パスワード処理の設計が必要です。PDFtk は input_pw をサポートしていますが、プロセスの引数にパスワードを含めると、プロセスの調査によって露出する可能性があります。パスワードをハードコードしたり、ログにコピーしたりしないでください。このチュートリアルのコマンドラインにシークレットを追加するのではなく、環境に適した安全なワークフローを使用してください。また、署名済み PDF を書き換えると、その署名は無効になります。
フィールド名や値の誤り
dump_data_fields_utf8 で、正確なフィールド名とエクスポート値を確認してください。フラット化していない結果を意図したマップと比較し、その後、フラット化した結果を目視で確認します。括弧、アンパサンド、引用符、バックスラッシュは、手書きの FDF エスケープ関数ではなく、XML シリアライザーが処理します。グリフが欠ける場合は、テンプレートに適切なフォントが必要です。XML のエンコーディングを変更しても解決しません。
