문서에서 Java를 사용한 바코드 특정 페이지 검색
소개
수백 개의 문서에서 서명을 수동으로 검증하는 데 시간을 보냈던 적이 있나요? 당신만 그런 것이 아닙니다. 계약 관리 시스템을 구축하든, 청구서 처리를 자동화하든, 의료 기록을 보호하든, 바코드 서명을 수동으로 추적하고 검증하는 일은 번거롭고 오류가 발생하기 쉽습니다. 이 튜토리얼에서는 GroupDocs.Signature와 함께 Java에서 바코드 페이지를 검색하는 방법을 배웁니다, 이를 통해 중요한 페이지만 프로그래밍 방식으로 타깃팅하고, 실시간 진행 상황을 모니터링하며, 몇 줄의 Java 코드만으로 다양한 바코드 형식을 처리할 수 있습니다.
배우게 될 내용
- Java 프로젝트에 GroupDocs.Signature 설정하기 (≈5 분)
- 실시간 진행 상황 추적을 위한 검색 이벤트 구독
- 특정 페이지를 타깃팅하는 스마트 검색 옵션 구성
- 검색을 실행하고 결과를 효율적으로 처리
빠른 답변
- 어떤 라이브러리가 바코드 특정 페이지 검색을 도와줍니다? Java용 GroupDocs.Signature
- 일반적인 설정 시간? 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 다운로드 페이지에서 직접 받을 수 있습니다.
라이선스 받기
- 무료 트라이얼 – 즉시 시작, 약정 없음
- 임시 라이선스 – 평가용 전체 기능 접근
- 정식 라이선스 – 프로덕션 준비, 무제한 사용
빠른 초기화 스니펫으로 설치를 확인합니다:
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자리 |
빠른 기계 판독, 구조화된 데이터 또는 변조 방지 서명이 필요할 때 바코드를 자주 사용합니다.
Java에서 바코드 페이지 검색 방법?
Signature는 처리할 문서를 나타내는 주요 클래스입니다. new Signature("file.pdf")로 문서를 로드하고, BarcodeSearchOptions가 바코드 서명 검색 매개변수를 정의하며, 원하는 페이지를 타깃팅하도록 구성한 뒤 signature.search(options)를 호출합니다. search 메서드는 제공된 옵션을 사용해 검색 작업을 실행하고, 페이지 번호, 디코딩된 텍스트 및 기하학적 좌표를 포함하는 BarcodeSignature 객체 리스트를 반환합니다. 이 한 단계 패턴은 별도의 이미지 추출이나 커스텀 디코딩 로직이 필요 없게 합니다.
전체 흐름을 이해했으니, 이제 구현할 세 가지 핵심 기능을 살펴보겠습니다.
기능 1: 문서 검색 이벤트 구독
왜 중요한가
대용량 배치를 처리할 때 실시간 피드백(예: 진행 바)은 UX를 개선하고 정체를 조기에 감지하는 데 도움이 됩니다.
정의 앵커
Signature는 문서를 나타내며 이벤트 구독 기능을 제공합니다.
구현
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");
}
});
이 세 핸들러는 시작 시간, 실시간 진행 상황, 최종 통계를 제공하여 로깅 또는 UI 업데이트에 적합합니다.
기능 2: 특정 페이지를 위한 바코드 검색 옵션 구성
세밀한 제어가 중요한 이유
200페이지 계약서 전체를 스캔하면 CPU 사이클이 낭비됩니다. 첫 페이지와 마지막 페이지만 타깃팅하면 실행 시간이 **최대 80 %**까지 단축됩니다.
정의 앵커
PagesSetup은 검색 작업에 포함될 페이지를 지정합니다.
구현
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는 감지된 바코드를 나타내며 페이지 번호와 디코딩된 텍스트와 같은 속성을 포함합니다.
구현
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‑인코딩된 인증서 해시 자동 검증 |
| 공급망 추적 | 선적 ID가 포함된 Code128을 청구서 첫/마지막 페이지에서 찾기 |
| 의료 동의서 | 최종 동의 페이지에서 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가 두 페이지만 검색하도록 제한하면 ~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: 한 번의 호출로 여러 바코드 형식을 검색할 수 있나요?
A: 예. BarcodeSearchOptions는 기본적으로 지원되는 모든 형식을 검색합니다. 특정 형식만 필요하면 getEncodeType()으로 결과를 필터링하세요.
Q: 바코드와 이미지 서명이 모두 포함된 문서는 어떻게 처리하나요?
A: 별도 검색을 수행합니다—바코드에는 BarcodeSignature.class, 이미지 서명에는 ImageSignature.class를 사용하고, 필요에 따라 결과를 결합합니다.
Q: 모든 페이지를 검색할 때와 특정 페이지만 검색할 때 성능 차이는 어느 정도인가요?
A: 50페이지 PDF 전체 스캔은 3–5 초가 소요될 수 있습니다. 첫 + 마지막 페이지만 제한하면 보통 1초 이하로 완료됩니다.
Q: 스캔된 PDF(래스터 이미지)에서도 작동하나요?
A: 바코드가 디지털 서명 객체로 추가된 경우에만 작동합니다. 래스터 전용 바코드의 경우 이미지 기반 바코드 인식기(예: GroupDocs.Barcode)가 필요합니다.
Q: 바코드 서명이 변조되지 않았는지 어떻게 검증하나요?
A: 바코드 페이로드에 해시 또는 디지털 서명을 삽입하고, 원본 데이터에 대해 해시를 재계산한 뒤 비교합니다. 이를 위해 원본 서명 키 또는 인증서가 필요합니다.
Last Updated: 2026-06-21
Tested With: GroupDocs.Signature 23.12 for Java
Author: GroupDocs