Java を使用したドキュメント内の特定ページのバーコード検索
はじめに
何百ものドキュメントの署名を手作業で検証するのに何時間も費やしたことはありませんか? あなたは一人ではありません。契約管理システムの構築、請求書処理の自動化、医療記録の保護など、バーコード署名を手動で追跡し検証するのは手間がかかり、エラーが起きやすい作業です。このチュートリアルでは GroupDocs.Signature を使用して Java でバーコードページを検索する方法を学びます。これにより、重要なページだけをプログラムで対象にし、リアルタイムで進捗を監視し、数行の Java コードでさまざまなバーコード形式を処理できます。
学べること
- 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 を提供します。20 種類以上のバーコード形式をサポートし、メモリに全ファイルをロードせずに数百ページのドキュメントを処理できるため、ファイル解析ではなくビジネスロジックに集中できます。
前提条件
- 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'
手動ダウンロードを好みますか? 最新リリースは GroupDocs ダウンロードページ から直接取得できます。
ライセンスの取得
- 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.");
}
}
プロのコツ:
"YOUR_DOCUMENT_PATH"を実際の PDF、DOCX、または XLSX ファイルに置き換えてください。コンソールに成功メッセージが表示されれば、準備完了です。
バーコード署名タイプの理解
バーコードは、ドキュメント内に機械可読データを埋め込みます。手書き署名とは異なり、ID、タイムスタンプ、URL、JSON ペイロードなどを格納でき、自動検証に最適です。
| バーコードタイプ | 最適な用途 | 典型的なデータ長 |
|---|---|---|
| QR Code | 高密度データ、URL、複数行テキスト | 最大 4,296 文字 |
| Code128 | 英数字の追跡番号 | 可変 |
| Code39 | シンプルなレガシーコード | 最大 43 文字 |
| DataMatrix | 小さなラベル、医療記録 | 最大 2,335 文字 |
| EAN/UPC | 製品識別、リテール | 8‑13 桁 |
高速な機械読み取り、構造化データ、改ざん防止署名が必要な場合にバーコードを頻繁に使用します。
Java でバーコードページを検索する方法は?
Signature は処理対象のドキュメントを表す主要クラスです。new Signature("file.pdf") でドキュメントをロードし、BarcodeSearchOptions がバーコード署名検索のパラメータを定義します。対象ページを設定し、signature.search(options) を呼び出します。search メソッドは指定オプションで検索を実行し、ページ番号、デコードテキスト、ジオメトリ座標を含む BarcodeSignature オブジェクトのリストを返します。このワンステップパターンにより、画像抽出やカスタムデコードロジックが不要になります。
全体の流れが理解できたら、実装する 3 つのコア機能に進みましょう。
機能 1: ドキュメント検索イベントの購読
なぜ重要か
大規模バッチを処理する際、リアルタイムのフィードバック(例:プログレスバー)は UX を向上させ、スタックを早期に検出できます。
定義アンカー
Signature がドキュメントを表し、イベント購読機能を提供します。
Implementation
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 % 短縮できます。
定義アンカー
PagesSetup が検索操作に含めるページを指定します。
Implementation
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)。 setAllPagesとPagesSetupを調整して 特定ページのバーコード検索 のみを実行します。
機能 3: 検索の実行と結果の処理
なぜこのステップが重要か
バーコードを見つけるだけでは不十分です。データを検証・保存・ワークフロー起動などに活用する必要があります。
定義アンカー
BarcodeSignature は検出されたバーコードを表し、ページ番号やデコードテキストなどのプロパティを保持します。
Implementation
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);
対象ページを絞ることで処理時間が大幅に短縮されます。150 ページの PDF でも、2 ページに限定すれば約 4 秒から 1 秒未満に削減できます。
問題 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-06-21
テスト環境: GroupDocs.Signature 23.12 for Java
作者: GroupDocs