Java を使用したドキュメント内の特定ページでバーコード検索

はじめに

何百ものドキュメントで手作業で署名を検証するのに何時間も費やしたことはありませんか? あなたは一人ではありません。契約管理システムを構築したり、請求書処理を自動化したり、医療記録を保護したりする場合でも、バーコード署名を手動で追跡して検証するのは手間がかかり、エラーが起きやすい作業です。

このガイドでは Java と GroupDocs.Signature を使用して、ドキュメント内の特定ページでバーコード署名を検索する方法 を示します。最後まで読めば、選択したページで署名を検出し、リアルタイムで検索進行状況を監視し、さまざまなバーコード形式に対応したクリーンで保守しやすいコードを書けるようになります。

学べること

  • Java プロジェクトに GroupDocs.Signature を設定する(約5分)
  • リアルタイム進行状況追跡のために検索イベントを購読する
  • 特定ページを対象にしたスマート検索オプションを構成する
  • 検索を実行し、結果を効率的に処理する

クイック回答

  • どのライブラリが特定ページでバーコード検索を支援しますか? GroupDocs.Signature for Java
  • 典型的なセットアップ時間は? Maven/Gradle 依存関係とライセンスを追加するのに約5分
  • 最初と最後のページだけに検索を限定できますか? はい – PagesSetup を使用して正確なページを指定します
  • サポートされているバーコード形式は? QR Code、Code128、Code39、DataMatrix、EAN/UPC など多数
  • 本番環境で有料ライセンスが必要ですか? 本番利用にはフルライセンスが必要です。評価用にトライアルも利用可能です

「特定ページでバーコード検索」とは?

特定ページでバーコード検索するとは、署名エンジンに対して「指定したページ(例:最初のページ、最後のページ、または任意のカスタム範囲)だけでバーコード署名を探す」よう指示することです。このフォーカスされたアプローチにより処理速度が向上し、メモリ使用量が削減され、レスポンシブな UI フィードバックを実装しやすくなります。

なぜこのタスクに GroupDocs.Signature を使用するのか?

GroupDocs.Signature は、低レベルのバーコードデコード、ページレンダリング、ドキュメント形式処理を抽象化したハイレベル API を提供します。PDF、DOCX、XLSX など多数の形式を箱から出すだけで扱えるため、ファイル解析に時間を取られることなくビジネスロジックに集中できます。

前提条件

  • JDK 8+ がインストール済み
  • Maven または Gradle による依存関係管理
  • Java のクラス、メソッド、例外処理に関する基本的な知識
  • GroupDocs.Signature のライセンス(トライアルまたはフル)へのアクセス

Java 用 GroupDocs.Signature の設定

Maven の設定

pom.xml に以下の依存関係を追加してください:

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-signature</artifactId>
    <version>23.12</version>
</dependency>

Gradle の設定

または build.gradle に追加します:

implementation 'com.groupdocs:groupdocs-signature:23.12'

Prefer manual downloads? You can grab the latest release directly from the GroupDocs download page.

ライセンスの取得

  • Free Trial – すぐに開始、コミット不要
  • Temporary License – 評価用にフル機能を利用可能
  • Full License – 本番環境向け、無制限使用

インストールが正しく行われたかを、以下の初期化スニペットで確認してください:

import com.groupdocs.signature.Signature;

public class SignatureSetup {
    public static void main(String[] args) {
        // Initialize the Signature instance with the document path
        Signature signature = new Signature("YOUR_DOCUMENT_PATH");
        
        System.out.println("GroupDocs.Signature for Java initialized successfully.");
    }
}

Pro tip: "YOUR_DOCUMENT_PATH" を実際の PDF、DOCX、または XLSX ファイルに置き換えてください。コンソールに成功メッセージが表示されれば、準備完了です。

バーコード署名タイプの理解

バーコードはドキュメント内に機械可読データを埋め込む手段です。手書き署名とは異なり、ID、タイムスタンプ、URL、JSON ペイロードなどを格納できるため、機械的な検証に最適です。

バーコードタイプ最適な使用例典型的なデータ長
QR Code高密度データ、URL、複数行テキスト最大4,296文字
Code128英数字の追跡番号可変
Code39シンプルなレガシーコード最大43文字
DataMatrix小さなラベル、医療記録最大2,335文字
EAN/UPC製品識別、リテール8〜13桁

高速な機械読み取り、構造化データ、改ざん検知が必要な場面でバーコードは頻繁に使用されます。

特定ページでバーコードを検索する方法

実装は以下の 3 つの機能に分割します。

機能 1: ドキュメント検索イベントへのサブスクライブ

なぜ重要か

大規模バッチを処理する際、リアルタイムのフィードバック(プログレスバーなど)は UX を向上させ、スタックを早期に検知できます。

実装

Signature signature = new Signature("YOUR_DOCUMENT_PATH");
signature.SearchStarted.add(new ProcessStartEventHandler() {
    public void invoke(Signature sender, ProcessStartEventArgs args) {
        System.out.println("Search process started at " + args.getStarted()
            + " with " + args.getTotalSignatures() + " total signatures to be put in document");
    }
});

signature.SearchProgress.add(new ProcessProgressEventHandler() {
    public void invoke(Signature sender, ProcessProgressEventArgs args) {
        System.out.println("Search progress. Processed " + args.getProcessedSignatures()
            + " signatures. Time spent " + args.getTicks() + " mlsec");
    }
});

signature.SearchCompleted.add(new ProcessCompleteEventHandler() {
    public void invoke(Signature sender, ProcessCompleteEventArgs args) {
        System.out.println("Search process completed at " + args.getCompleted()
            + " with " + args.getTotalSignatures() + " total signatures. Process took "
            + args.getTicks() + " mlsec");
    }
});

これら 3 つのハンドラにより、開始時刻、リアルタイム進行状況、最終統計が取得でき、ロギングや UI 更新に最適です。

機能 2: 特定ページ用のバーコード検索オプションの設定

なぜ細かい制御が重要か

200 ページの契約書全体をスキャンすると CPU が無駄に消費されます。最初と最後のページだけを対象にすれば、実行時間を 80 % 以上短縮できます。

実装

import com.groupdocs.signature.domain.enums.TextMatchType;
import com.groupdocs.signature.options.search.BarcodeSearchOptions;

BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setAllPages(false); // Opt‑in selective page searching
options.setPageNumber(1);   // Starting page (optional)
import com.groupdocs.signature.options.PagesSetup;

PagesSetup pagesSetup = new PagesSetup();
pagesSetup.setFirstPage(true);   // Include first page
pagesSetup.setLastPage(true);    // Include last page
pagesSetup.setOddPages(false);   // Skip odd pages
pagesSetup.setEvenPages(false);  // Skip even pages
options.setPagesSetup(pagesSetup);
options.setMatchType(TextMatchType.Contains);
options.setText("12345");
  • Match types によりテキスト検索を細かく調整できます(Contains, Exact, StartsWith, EndsWith)。
  • setAllPagesPagesSetup を調整して、特定ページでのみバーコード検索 を行います。

機能 3: 検索の実行と結果の処理

なぜこのステップが重要か

バーコードを見つけるだけでは不十分です。取得したデータを検証・保存・ワークフロー起動などに活用する必要があります。

実装

import java.util.List;
import com.groupdocs.signature.domain.signatures.BarcodeSignature;

try {
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
    System.out.println("Source document contains following signatures.");
    
    for (BarcodeSignature barcodeSignature : signatures) {
        System.out.println("Barcode signature found at page " + barcodeSignature.getPageNumber()
            + " with type " + barcodeSignature.getEncodeType() + " and text " + barcodeSignature.getText());
    }
} catch (Exception e) {
    throw new RuntimeException(e.getMessage(), e);
}

検索後は BarcodeSignature オブジェクトのリストが取得でき、以下の情報が利用可能です。

  • getPageNumber() – バーコードが存在するページ番号
  • getEncodeType() – QR、Code128 などのエンコード種別
  • getText() – デコードされたペイロード
  • 位置情報(getLeft(), getTop())とサイズ(getWidth(), getHeight()

例: 最終ページの QR コードだけを処理する

for (BarcodeSignature barcodeSignature : signatures) {
    if (barcodeSignature.getPageNumber() == lastPageNumber 
        && barcodeSignature.getEncodeType().equals("QRCode")) {
        // Process only QR codes from the final page
        processApprovalCode(barcodeSignature.getText());
    }
}

実際の活用例

シナリオバーコード特定ページ検索の利点
法的契約の検証署名ページで QR コードでエンコードされた証明書ハッシュを自動検証
サプライチェーン追跡マニフェストの最初/最後のページで Code128 の出荷 ID を検索
医療同意書最終同意ページから DataMatrix の患者 ID を抽出
請求書の自動化請求書内の “APPR‑” プレフィックス付きバーコードを検索し、ルーティング

よくある問題と解決策

問題 1 – バーコードが見えているのに結果が出ない

// Ensure you are not limiting pages too aggressively
options.setAllPages(true);

バーコードがラスタ画像として埋め込まれている場合は、画像ベースの検出用に GroupDocs.Image の使用を検討してください。

問題 2 – 大きなファイルでのパフォーマンス低下

PagesSetup pagesSetup = new PagesSetup();
pagesSetup.setLastPage(true);  // Most signatures are on the last page
pagesSetup.setFirstPage(true);
options.setPagesSetup(pagesSetup);

対象ページを絞るだけで処理時間が大幅に短縮されます。

問題 3 – TextMatchType が期待したバーコードを見つけない

String searchText = "12345".trim().toLowerCase();
options.setText(searchText);
options.setMatchType(TextMatchType.StartsWith); // Try a more permissive mode

問題 4 – 長時間ループでのメモリリーク

try (Signature signature = new Signature("document.pdf")) {
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
    // Process signatures
}

try‑with‑resources ブロックが Signature インスタンスを自動的に破棄します。

本番環境でのベストプラクティス

堅牢なエラーハンドリング

try {
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
} catch (com.groupdocs.signature.exception.GroupDocsSignatureException e) {
    logger.error("GroupDocs error: " + e.getMessage());
} catch (Exception e) {
    logger.error("Unexpected error: " + e.getMessage(), e);
}

ドキュメントが不変の場合は結果をキャッシュ

Map<String, List<BarcodeSignature>> cache = new ConcurrentHashMap<>();

public List<BarcodeSignature> getCachedSignatures(String docId) {
    return cache.computeIfAbsent(docId, id -> performSearch(id));
}

UI フィードバックにプログレスイベントを使用

signature.SearchProgress.add(new ProcessProgressEventHandler() {
    public void invoke(Signature sender, ProcessProgressEventArgs args) {
        int percent = (args.getProcessedSignatures() * 100) / args.getTotalSignatures();
        updateProgressBar(percent);
    }
});

バーコードペイロードの検証

for (BarcodeSignature barcodeSignature : signatures) {
    String text = barcodeSignature.getText();
    if (!text.matches("APPR-\\d{4}-\\d{3}")) {
        logger.warn("Invalid format: " + text);
        continue;
    }
    if (!validateChecksum(text)) {
        logger.error("Checksum failed for: " + text);
        flagForManualReview(document);
    }
}

ドキュメントタイプごとにページ選択を最適化

PagesSetup contractsSetup = new PagesSetup();
contractsSetup.setLastPage(true); // Contracts usually signed on last page
options.setPagesSetup(contractsSetup);

検索後にバーコードタイプでフィルタ (QR コードのみが必要な場合)

for (BarcodeSignature sig : signatures) {
    if ("QRCode".equals(sig.getEncodeType())) {
        // Process QR code
    }
}

バーコード画像の寸法を抽出 (レンダリングが必要な場合)

for (BarcodeSignature sig : signatures) {
    int width = sig.getWidth();
    int height = sig.getHeight();
    // Use dimensions for overlay or thumbnail generation
}

よくある質問

Q: 1回の呼び出しで複数のバーコード形式を検索できますか?
A: はい。BarcodeSearchOptions はデフォルトでサポートされているすべての形式を検索します。特定のタイプだけが必要な場合は getEncodeType() で結果をフィルタしてください。

Q: バーコード署名と画像署名の両方が含まれるドキュメントはどう扱いますか?
A: 別々に検索します。バーコードは BarcodeSignature.class、画像署名は ImageSignature.class を使用し、必要に応じて結果を統合します。

Q: すべてのページを検索する場合と特定ページだけを検索する場合のパフォーマンス差は?
A: 50 ページの PDF 全体をスキャンすると 3〜5 秒かかりますが、最初と最後のページだけに限定すれば 1 秒未満で完了することが多いです。

Q: スキャンした PDF(ラスタ画像)でも動作しますか?
A: バーコードがデジタル署名オブジェクトとして追加されている場合のみ有効です。ラスタ画像のみのバーコードは、画像ベースのバーコード認識ツール(例: GroupDocs.Barcode)を使用する必要があります。

Q: バーコード署名が改ざんされていないことをどう確認しますか?
A: バーコードペイロードにハッシュやデジタル署名を埋め込み、元データのハッシュと比較します。これには元の署名鍵または証明書が必要です。


最終更新日: 2026-01-29
テスト環境: GroupDocs.Signature 23.12 for Java
作成者: GroupDocs