技術記事

DelphiでのPDFフォーム結合:重複フィールドの規則

新しく結合した申請パックの1ページ目にあるApplicantボックスに名前を入力してタブで移動すると、多くのビューアでは6ページ目のApplicantボックスにも同じテキストが入ります。その2つのコントロールを結び付けた人はいません。パックのパート1とパート3は別人が作成し、どちらもトップレベルフィールドにApplicantと名付けました。PDFフォームはフィールドを完全修飾名で識別するため、ファイル形式の観点では、同じ名前の2つのフィールドは2回描かれた1つのフィールドです

対策は、結合が起こる前に共有名の意味を決めておくことです。拒否する、意図的に共有する、新参者の名前を変える。事後の判断は、聞こえ以上にずっと難しいものです

ISO 32000におけるフィールド名の意味

フィールド名は同一性であり、仕様もそう述べています。ISO 32000-1 §12.7.3.2は、フィールドとその各祖先の部分名(Tエントリ)をピリオドで連結して完全修飾名を組み立てます。同じ節は、複数のフィールド辞書が1つの完全修飾名を共有することを認め、それらを同一の基底フィールドの異なる表現と説明しています。見た目だけが異なるはずのものです。独立に作成された2つのフォームのFields配列を連結すると、まさにその配置が偶然生まれます

被害の形は、衝突したフィールドが何を保持していたかで決まります。片方のフォームでは生年月日、もう片方では署名日を意味していたDateは、値のスロットを1つしか持たず、ビューアがどちらの値に落ち着こうと、その値が両方の場所に入ります。経費シートのTotalと入金フォームのTotalは、どちらかが計算された瞬間に食い違います。署名フィールドが最悪のケースです。異なるページの2つの署名ウィジェット、1つの名前、そして署名者が実際に承認したのがどちらのウィジェットなのか、きれいな答えはありません

大文字小文字も問題になります。部分名はテキスト文字列であり、仕様のどこにも畳み込みの規定はないため、Totalとtotalは2つの別フィールドです。比較前に名前を小文字へ落とす衝突検査は、存在しない衝突を報告し、リネームポリシーの下では、誰も触れる必要のなかったフィールドをリネームします

何かを動かす前に名前を検査する

PDF Library for Delphiは、この衝突をMergeDocumentEx(DocumentID, DuplicateFieldStrategy)で処理します。DocumentIDで識別されるドキュメントを現在選択中のドキュメントへ結合し、1つのオブジェクトも番号付け替えが行われる前に、すべての名前衝突を片付けます。戦略はTPDFlibDuplicateFieldStrategyの値、すなわちdfsReject、dfsMerge、dfsAutoNumberです。素のMergeDocumentは相変わらず2つのルートフィールド配列を無変更で連結します。両方のフォームを自分で所有し、名前が重複しないと分かっているなら、それが正しい選択です

順序こそが設計のすべてです。結合は、取り込むドキュメントのオブジェクト番号を、ターゲットと衝突しないようずらし、そのページをターゲットのページツリーへ縫い付け、フィールドをフォームへ追加する必要があります。衝突がこれらのステップの後にだけ表面化するなら、拒否はもはや無償ではありません。ターゲットはすでにページを取り込み済みで、ソースのオブジェクトはどちらのファイルも最初に持っていなかった番号を背負い、呼び出し側に残された手は、両ファイルをディスクから読み直すことだけです。MergeDocumentExは、両ドキュメントのトップレベルフィールド名を、まず順序付きの大文字小文字を区別する集合へ収集し、その集合に対して戦略を適用します。dfsRejectの下では、衝突があると呼び出しは0を返し、LastErrorCodeが705に設定されます。両ドキュメントは読み込んだときのままであり、拒否の直後にソースドキュメントからフィールド値を読めば、元のテキストが返ってきます

スキャン自体は安価です。ターゲットにn個、ソースにm個の名前があるとき、1つの集合へソートするコストは(n + m) log(n + m)オーダーの比較回数です。数百フィールドのパックなら、ファイルのパースに比べて気付けるほどのコストは追加されません

PDF Library for Delphi: 操作順序の図。番号付け替えとページツリー縫合の後に重複フィールド名を発見する従来のマージと、MergeDocumentEx が名前を先に収集して拒否時も両ドキュメントを無傷に保つ方式の対比
番号の付け替えとページツリーの接合は、レガシーマージがフィールド名を調べるより前に起こるため、きれいなロールバックが残りません。MergeDocumentEx は順序付きの大文字小文字を区別する名前集合を事前に比較し、拒否をきれいな no-op に変えます

スキャンの3つの性質は、実際のフォームパックで顔を出します:

  • 比較されるのはトップレベルフィールドだけです。階層フォームでは親の部分名を意味するため、それぞれapplicantという親を持つ2つのフォームは、子が違っても衝突し、自動採番は親をリネームします。取り込まれた子はapplicant_2.name、applicant_2.addressとして読まれます
  • 取り込まれる名前は、検査されながら集合へ加わります。すでに同じ名前のトップレベルフィールドを2つ抱えたソースドキュメントは、ターゲットにその名前のフィールドがまったくなくても、2つ目で戦略に引っ掛かります
  • 部分名が空のフィールドはスキップされ、どちらかのドキュメントにAcroFormがなければ比較対象がないため、どんな戦略でも結合はそのまま進みます

読み込み側には、それ自身の罠が1つあります。LoadFromFileは新しいドキュメントをライブラリに追加して選択するため、取っておくべき識別子は、各読み込みの後にSelectedDocumentが返すものです。読み込みの前に取得すると、結合先だと思っているドキュメントとは別のものを掴んでいます

uses
  SysUtils, PDFlibrary;

procedure BuildPack(const Part1, Part2, OutFile: WideString);
var
  Lib: TPDFlib;
  TargetDoc, SourceDoc: Integer;
begin
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile(Part1, '') = 0 then
      raise Exception.CreateFmt('Cannot load %s', [Part1]);
    TargetDoc := Lib.SelectedDocument;   // 読み込みの後で読む。前ではない

    if Lib.LoadFromFile(Part2, '') = 0 then
      raise Exception.CreateFmt('Cannot load %s', [Part2]);
    SourceDoc := Lib.SelectedDocument;

    Lib.SelectDocument(TargetDoc);       // 選択中のドキュメントが結合を受け取る
    if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
    begin
      if Lib.LastErrorCode <> 705 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);

      // トップレベル名の重複。両ドキュメントとも無傷なので、
      // SourceDocはそのまま2回目の試行へ回せる
      WriteLn('Duplicate field names in ', Part2, ', retrying with auto-numbering');
      if Lib.MergeDocumentEx(SourceDoc, dfsAutoNumber) = 0 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);
    end;

    Lib.SaveToFile(OutFile);
  finally
    Lib.Free;
  end;
end;

最初に厳格に、次に寛容に。この2段構成が機能するのは、拒否がSourceDocを読み込んだまま無傷で残すからです。途中で失敗する結合なら、フォールバック分岐は両ファイルの読み直しから始めなければなりません。705そのものの検査も重要です。無効なドキュメント識別子や範囲外の戦略値は別のコードで呼び出しを失敗させ、別の戦略での再試行ではどちらも直らないからです

戦略の選択:拒否、共有、再採番

無人のパイプラインでは、dfsRejectをデフォルトにし、705をソースフォームの所有者へのチケットとして扱います。上流でフィールドを1回リネームするほうが、結合が勝手にTotal_2を生み出したせいで、エクスポートマッピングが数ヶ月後に黙って一致しなくなったと発見するより安上がりです。自動戦略が活きるのは、人間がフォームを見て共有名の意味を決めた後です

dfsMergeは、共有名を意図的に保持します。何かが追加される前に、ターゲットフィールドの値とデフォルト値が取り込むフィールドへコピーされるため、結合ファイルは一貫した状態で始まり、名前でウィジェットをグループ化するビューアには、1つの値を持つ1つの論理フィールドが見えます。2つのフィールド辞書は別オブジェクトのままで、それぞれ自身のページ、外観、アクションを保持します。1つの辞書へ畳み込むと、取り込むフォームに属する書式と挙動が捨てられます。見た目の単純化のためにそれを取る価値はありません

dfsAutoNumberは、取り込まれる重複フィールドを、_2から始まる数値接尾辞の追加でリネームし、最初に空いている番号を使います。ターゲットにすでにSharedとShared_2があれば、新参者はShared_3になります。結果は存在する名前だけに依存し、オブジェクト番号には決して依存しないため、同じ2ファイルのペアを2回結合しても、両方とも同じ名前になります。下流のFDFインポートやデータベースマッピングが頼りにする性質です

PDF Library for Delphi の MergeDocumentEx 後の 3 つの重複フィールド結果。dfsReject は両フォームを無傷のままエラー 705 を返し、dfsMerge は同名ウィジェットを 1 つの論理値へ同期、dfsAutoNumber は再現可能な _2 接尾辞を追加
dfsReject は両方のドキュメントを手つかずのまま保ち、状況を踏まえた再試行を可能にします。dfsMerge は同名の複数ウィジェットを、同期された 1 つの値を持つ 1 つの論理フィールドとして扱います。dfsAutoNumber は安定した接尾辞付きの名前を割り振るため、外部マッピング側はそれを織り込んでおく必要があります

2つの自動戦略の選択は、1つの問いに帰着します。片方のコントロールを埋めたら、もう片方も埋めるべきか? パックの全パーツに繰り返し現れる署名者名なら、答えはイエスで、dfsMergeが合います。フォームごとに計算方法の違う合計なら、答えはノーです。そこではdfsAutoNumberを選ぶか、さらに良くするにはソースフォームのフィールドをリネームして、接尾辞が決して現れないようにします

結合後のフォームには何が入っているのか

「Target value」を保持するトップレベルテキストフィールドSharedを持つターゲットと、自身のSharedを持つソースを考えます。dfsMergeの後、FormFieldCountは2つのフィールドを数え、どちらもタイトルはShared、どちらも「Target value」を報告します。dfsAutoNumberの後、同じ入力はSharedとShared_2を生み、取り込まれたフィールドはソースファイルで持っていた値をそのまま保ちます

dfsMergeの結果には鋭い刃があり、それは自分の記入コードの中にあります。FindFormFieldByTitleはタイトルが一致する最初のインデックスを返し、SetFormFieldValueは正確に1つのフィールドへ書き込みます。Sharedを1回検索して設定するルーチンは、ターゲット側のコピーを更新し、取り込まれたコピーには結合時に受け取った値を残したままにします。保存されたファイルには、1つの名前と2つの異なる値を持つ2つのフィールドが含まれ、ビューアがどちらを表示するかはビューア次第です。代わりに、一致するすべてに書き込みます:

// Titleを持つすべてのフィールドを設定する。書き込めた数を返す。
// dfsMergeの結合後、1つの論理フィールドが複数のインデックスに現れ得る
function SetAllFieldsNamed(Lib: TPDFlib; const Title, Value: WideString): Integer;
var
  I: Integer;
begin
  Result := 0;
  for I := 1 to Lib.FormFieldCount do
    if Lib.GetFormFieldTitle(I) = Title then
    begin
      if Lib.SetFormFieldValue(I, Value) = 1 then
        Inc(Result)
      else
        WriteLn(Format('Field %d (%s) not written, error %d',
          [I, Title, Lib.LastErrorCode]));   // 読み取り専用フィールドはここに来る
    end;
end;

結合したパックをデータフィードに繋ぐ前に、結合が実際に何を生んだかをダンプします。2行のループで足り、インポートジョブより先に、リネームされた親と_2接尾辞を捕まえます:

for I := 1 to Lib.FormFieldCount do
  WriteLn(Format('%3d  %-30s  %s',
    [I, Lib.GetFormFieldTitle(I), Lib.GetFormFieldValue(I)]));

実務でのフォームパックの組み立て

成功した結合はソースドキュメントを消費します。ライブラリのドキュメントリストから取り除かれるため、DocumentCountは1つ減り、古いSourceDoc識別子を二度と使ってはなりません。結合ドキュメントは2つのPDFバージョンの高い方を採ります。PDF 2.0のフォームを1.7のドキュメントへ結合すると、2.0のファイルが生まれます。下流のアーカイブステップが特定バージョンを期待しているなら、これは重要です

結合順序が、どちらの名前が生き残るかを決めます。選択中のドキュメントは自分の名前をすべて保持し、リネームや値のコピーは取り込む側のフィールドにしか適用されないため、AをBへ結合するのとBをAへ結合するのは、異なる自動採番結果になります。パックに主フォームがあるなら、つまりバックオフィスがすでに知っているフィールド名を持つフォームがあるなら、それをターゲットにし、補足フォームをそこへ結合します

署名は最後に。署名は署名した版のバイト列をカバーし、結合はファイルを書き直すため、組み立て前に署名されたパートは、もはやドキュメントと一致する署名を運びません。パックを組み立て、フィールド一覧を確認し、それから完成ファイルへ署名を適用します。仕事がページの縫い合わせだけのもので、フォームが重要でないなら、バイト参照シフトによる高速PDF結合のほうが速い道です

結合と並行して、データ側の計画も立てます。フィールドの値が、名前でフィールドをアドレスする外部システムから届くなら、dfsAutoNumberを選ぶ前に名前の付け方を決めておきます。Shared_2は、Sharedを期待するマッピングとは一致しません。値のインポート・エクスポート形式はFDF、XFDF、XFAによるフォームデータ交換で扱います。名前でフィールドを参照する計算スクリプトやアクションも、リネームの影響を同じように受けます。インタラクティブフォームアクションとJavaScriptが、それらの参照がどこにあるかを示します

重複を意識したフォーム結合、フィールド記入、電子署名は、Delphi、C++Builder、Free Pascalプロジェクト向けの同じライブラリの一部です。フォームとドキュメント組み立てAPIの残りは、PDF Library for Delphi製品ページに一覧されています