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'
수동 다운로드를 선호하시나요? 최신 릴리스를 바로 GroupDocs download page에서 받을 수 있습니다.
라이선스 받기
- 무료 트라이얼 – 즉시 시작, 약정 없음
- 임시 라이선스 – 평가용 전체 기능 제공
- 정식 라이선스 – 프로덕션 준비, 무제한 사용
다음 초기화 스니펫으로 설치를 확인하세요:
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자리 |
빠른 기계 판독, 구조화된 데이터, 변조 방지 서명이 필요할 때 바코드를 자주 사용합니다.
바코드 특정 페이지 검색 방법
구현을 세 가지 핵심 기능으로 나누어 설명합니다.
기능 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");
}
});
이 세 핸들러는 시작 시간, 실시간 진행 상황, 최종 통계를 제공하므로 로깅이나 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). setAllPages와PagesSetup을 조정해 바코드 특정 페이지만 검색하도록 설정하세요.
기능 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‑코드로 인코딩된 인증서 해시 자동 검증 |
| 공급망 추적 | 선적 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);
대상 페이지만 지정하면 처리 시간이 크게 감소합니다.
문제 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-01-29
Tested With: GroupDocs.Signature 23.12 for Java
Author: GroupDocs