LlosLab Software Development BlogEngineering notes for PDF, Delphi, and document software developers.

技術記事

PDFium Component: Delphi での PreflightReportCli batch validation

PDFium Component

Delphi/C++Builder には PDFium VCL Component のワークフローを、Lazarus/FPC には PDFium LCL Component のワークフローを組み込み、表示、レンダリング、フォーム、印刷、プリフライトレポート、標準対応の検証をソースコード付きコンポーネントで実装できます。

この記事は teams integrating command-line PDF validation into build, intake, archive, or customer-processing pipelines 向けです。PreflightReportCli batch validation を単なるコンポーネント呼び出しではなく、本番向けのドキュメントエンジニアリングとして扱います。

実務上のリスクは batch validation is only useful if exit codes, timeouts, report paths, severity thresholds, and retry behavior are stable enough for automation です。そのため、明確な契約、観測可能な診断、実際の顧客ファイルに近い回帰サンプルが必要です。

アーキテクチャ上の判断

Design the CLI as a contract for automation. profile selection, fail-on severity, report format, and output directory layout / exit-code mapping for pass, warning, failure, timeout, bad input, and internal error

  • profile selection, fail-on severity, report format, and output directory layout
  • exit-code mapping for pass, warning, failure, timeout, bad input, and internal error
  • parallelism, maximum file size, quarantine path, and retry rules
  • how structured reports are retained with tickets, builds, or customer jobs

実装フロー

Map validation findings to process outcomes. The order below keeps the workflow reviewable for Delphi and C++Builder teams.

  1. standardize command-line arguments before wiring the tool into schedulers
  2. run one file per isolated job so timeouts and failures do not poison the batch
  3. write human and machine reports to deterministic locations
  4. translate findings into pass, review, block, or quarantine states
  5. summarize the batch with counts by severity, profile, and outcome

検証エビデンス

Batch evidence that makes failures actionable. Keep these fields with the output or support record.

  • command arguments, profile version, file count, elapsed time, and exit code
  • per-file report path, status, issue count, highest severity, and failure reason
  • timeout, retry, quarantine, and cleanup actions
  • machine-readable summary attached to the automated job record

Exit codes should reflect business policy

A preflight CLI is a bridge between PDF analysis and automation. It should produce predictable reports for people, structured output for machines, and clear exit behavior for schedulers and CI systems.

Regression files worth keeping

Keep more than successful samples. A useful PreflightReportCli batch validation regression set contains normal files, boundary files, and intentional failure files so the behavior is stable across releases.

  • one corrupt file should not prevent reports for all remaining files
  • warnings may need to fail CI but only flag intake jobs for manual review
  • parallel processing should not write reports with colliding names
  • operators need a stable difference between validation failure and tool failure
  • standardize command-line arguments before wiring the tool into schedulers
  • run one file per isolated job so timeouts and failures do not poison the batch

PreflightReportCli batch validation に関する技術レビューの注意点

これらのレビュー項目を使って、機能がデモ段階を超え、リリース、サポート、顧客エスカレーションの場で説明できることを確認します

  • 判断: profile selection, fail-on severity, report format, and output directory layout. 実装上の焦点: run one file per isolated job so timeouts and failures do not poison the batch. 受け入れ証拠: timeout, retry, quarantine, and cleanup actions. 回帰の引き金: operators need a stable difference between validation failure and tool failure
  • 判断: exit-code mapping for pass, warning, failure, timeout, bad input, and internal error. 実装上の焦点: write human and machine reports to deterministic locations. 受け入れ証拠: machine-readable summary attached to the automated job record. 回帰の引き金: one corrupt file should not prevent reports for all remaining files
  • 判断: parallelism, maximum file size, quarantine path, and retry rules. 実装上の焦点: translate findings into pass, review, block, or quarantine states. 受け入れ証拠: command arguments, profile version, file count, elapsed time, and exit code. 回帰の引き金: warnings may need to fail CI but only flag intake jobs for manual review
  • 判断: how structured reports are retained with tickets, builds, or customer jobs. 実装上の焦点: summarize the batch with counts by severity, profile, and outcome. 受け入れ証拠: per-file report path, status, issue count, highest severity, and failure reason. 回帰の引き金: parallel processing should not write reports with colliding names
  • 判断: profile selection, fail-on severity, report format, and output directory layout. 実装上の焦点: standardize command-line arguments before wiring the tool into schedulers. 受け入れ証拠: timeout, retry, quarantine, and cleanup actions. 回帰の引き金: operators need a stable difference between validation failure and tool failure
  • 判断: exit-code mapping for pass, warning, failure, timeout, bad input, and internal error. 実装上の焦点: run one file per isolated job so timeouts and failures do not poison the batch. 受け入れ証拠: machine-readable summary attached to the automated job record. 回帰の引き金: one corrupt file should not prevent reports for all remaining files

境界ケース

  • one corrupt file should not prevent reports for all remaining files
  • warnings may need to fail CI but only flag intake jobs for manual review
  • parallel processing should not write reports with colliding names
  • operators need a stable difference between validation failure and tool failure

Delphi / C++Builder の補足

PDFium Component should sit behind a small service boundary that receives files, streams, profiles, and credentials, then returns output paths, warnings, metrics, and validation status. 重要な用語には PreflightReportCli, batch validation, exit code, severity, report path, timeout.

Delphi コード例

次の Delphi スケッチは、このテーマに対する実用的なサービス境界を示します。ポリシー確認、ログ記録、検証を製品呼び出しの狭い部分の外側に置くと、ワークフローをテストしやすくなります。

procedure RunPdfiumBatch(const Files: TArray<string>; const OutputDir: string);
var
  FileName: string;
begin
  for FileName in Files do
  begin
    PdfView.LoadFromFile(FileName);
    WritePreflightJson(OutputDir, FileName, InspectDocument(PdfView));
    PdfView.Close;
  end;
  WriteBatchSummary(OutputDir);
end;

本番チェックリスト

  • ワークフローは、空のファイル、通常の顧客ファイル、最悪ケースのファイルで実行します
  • 生成された PDF は、対象のビューアー、検証ツール、プリンター、または downstream アプリケーションで開きます
  • 製品バージョン、プロファイルバージョン、入力ハッシュ、出力パス、経過時間、警告数を記録します
  • パスワード、証明書、一時ファイル、顧客データは明確な保持ルールの下で管理します
  • 顧客ファイルが新しい境界ケースを示したら、回帰用ドキュメントを追加します

製品ドキュメント

PDFium Component

追加のコード例

procedure RunPreflightBatch(const InputDir, ReportDir: string;
  out FilesWithFindings, ToolFailures: Integer);
var
  SR: TSearchRec;
  Pdf: TPdf;
  Report: TPdfPreflightReport;
begin
  FilesWithFindings := 0;
  ToolFailures := 0;
  if FindFirst(InputDir + '*.pdf', faAnyFile, SR) = 0 then
  try
    repeat
      Pdf := TPdf.Create(nil);   // fresh instance per file: no state bleed
      try
        try
          Pdf.FileName := InputDir + SR.Name;
          Pdf.Active := True;
          if not Pdf.Active then  // load failures are silent, not raised
            raise EPdfError.Create('Cannot open ' + SR.Name);
          Report := BuildPdfPreflightReport(Pdf, [ppsPdfA, ppsPdfUa]);
          Report.SaveJsonToFile(ReportDir + ChangeFileExt(SR.Name, '.json'));
          Report.SaveHtmlToFile(ReportDir + ChangeFileExt(SR.Name, '.html'));
          if Report.TotalIssueCount > 0 then
            Inc(FilesWithFindings);
        except
          on E: Exception do
          begin
            Inc(ToolFailures);   // exit-code-2 territory, not a validation verdict
            WriteLn(ErrOutput, SR.Name + ': ' + E.Message);
          end;
        end;
      finally
        Pdf.Free;
      end;
    until FindNext(SR) <> 0;
  finally
    FindClose(SR);
  end;
end;
begin
  RunPreflightBatch(ParamStr(1), ParamStr(2), Findings, Failures);
  if Failures > 0 then
    Halt(2)
  else if Findings > 0 then
    Halt(1);
  // falling through exits with 0: every file conformed
end.