문서에서 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

관련 튜토리얼