Cerca pagine specifiche di barcode nei documenti usando Java

Introduzione

Hai mai passato ore a verificare manualmente le firme su centinaia di documenti? Non sei solo. Che tu stia costruendo un sistema di gestione contratti, automatizzando l’elaborazione delle fatture o proteggendo i record sanitari, rintracciare e convalidare manualmente le firme barcode è noioso e soggetto a errori. In questo tutorial imparerai come cercare pagine barcode in Java con GroupDocs.Signature, così potrai mirare programmaticamente solo alle pagine rilevanti, monitorare il progresso in tempo reale e gestire una varietà di formati barcode con poche righe di codice Java.

What you’ll learn

• Configurare GroupDocs.Signature in un progetto Java (≈5 minuti)
• Iscriversi agli eventi di ricerca per il monitoraggio del progresso in tempo reale
• Configurare opzioni di ricerca intelligenti per mirare a pagine specifiche
• Eseguire la ricerca e processare i risultati in modo efficiente

Risposte rapide

• Which library helps you search barcode specific pages? GroupDocs.Signature for Java
• Typical setup time? About 5 minutes to add the Maven/Gradle dependency and a license
• Can I limit the search to the first and last pages? Yes – use PagesSetup to specify exact pages
• What barcode formats are supported? QR Code, Code128, Code39, DataMatrix, EAN/UPC, and more
• Do I need a paid license for production? A full license is required for production; a trial works for evaluation

Che cosa significa “search barcode specific pages”?

Cercare pagine barcode specifiche significa istruire il motore di firma a cercare firme barcode solo sulle pagine di tuo interesse—ad esempio la prima pagina, l’ultima pagina o qualsiasi intervallo personalizzato. Questo approccio mirato velocizza l’elaborazione, riduce l’uso di memoria e consente di costruire un feedback UI reattivo.

Perché usare GroupDocs.Signature per questo compito?

GroupDocs.Signature fornisce un’API di alto livello che astrae la decodifica barcode a basso livello, il rendering delle pagine e la gestione dei formati di documento. Supporta oltre 20 formati barcode e può elaborare documenti con centinaia di pagine senza caricare l’intero file in memoria, permettendoti di concentrarti sulla logica di business anziché sul parsing dei file.

Prerequisiti

• JDK 8+ installato
• Maven o Gradle per la gestione delle dipendenze
• Familiarità di base con classi Java, metodi e gestione delle eccezioni
• Accesso a una licenza GroupDocs.Signature (trial o completa)

Configurazione di GroupDocs.Signature per Java

Configurazione Maven

Aggiungi la dipendenza al tuo pom.xml:

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

Configurazione Gradle

Oppure includila in build.gradle:

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

Preferisci download manuali? Puoi scaricare l’ultima release direttamente dalla GroupDocs download page.

Ottenere la tua licenza

• Free Trial – inizia subito, senza impegno
• Temporary License – accesso completo alle funzionalità per la valutazione
• Full License – pronta per la produzione, utilizzo illimitato

Verifica l’installazione con un rapido snippet di inizializzazione:

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: Sostituisci "YOUR_DOCUMENT_PATH" con un file PDF, DOCX o XLSX reale. Se la console stampa il messaggio di successo, sei pronto per procedere.

Comprendere i tipi di firma Barcode

I barcode incorporano dati leggibili da macchine all’interno di un documento. A differenza delle firme manoscritte, possono memorizzare ID, timestamp, URL o payload JSON, rendendoli ideali per la verifica automatizzata.

Spesso utilizzerai i barcode quando hai bisogno di lettura veloce da macchina, dati strutturati o firme a prova di manomissione.

Come cercare pagine barcode in Java?

Signature è la classe principale che rappresenta un documento da elaborare. Carica il documento con new Signature("file.pdf"), BarcodeSearchOptions definisce i parametri per la ricerca di firme barcode, configurala per mirare alle pagine desiderate e chiama signature.search(options). Il metodo search esegue l’operazione di ricerca usando le opzioni fornite. Il motore restituisce un elenco di oggetti BarcodeSignature che contengono numeri di pagina, testo decodificato e coordinate geometriche—tutto in una singola chiamata. Questo modello a un passo elimina la necessità di estrarre immagini separatamente o di implementare logiche di decodifica personalizzate.

Ora che hai compreso il flusso generale, approfondiamo le tre funzionalità principali che implementerai.

Feature 1: Iscriversi agli eventi di ricerca del documento

Perché è importante

Quando si elaborano grandi lotti, un feedback in tempo reale (ad es. barre di avanzamento) migliora l’esperienza utente e aiuta a rilevare blocchi precocemente.

Ancoraggio della definizione

Signature rappresenta il documento e fornisce capacità di sottoscrizione agli eventi.

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");
    }
});

Questi tre gestori ti forniscono tempo di avvio, progresso in tempo reale e statistiche finali—perfetti per logging o aggiornamenti UI.

Feature 2: Configurare le opzioni di ricerca Barcode per pagine specifiche

Perché il controllo granulare è importante

Scansionare ogni pagina di un contratto di 200 pagine spreca cicli CPU. Mirare solo alla prima e all’ultima pagina può ridurre il tempo di esecuzione fino al 80 %.

Ancoraggio della definizione

PagesSetup specifica quali pagine sono incluse nell’operazione di ricerca.

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");

• I tipi di corrispondenza ti permettono di affinare la ricerca di testo (Contains, Exact, StartsWith, EndsWith).
• Regola setAllPages e PagesSetup per cercare solo pagine barcode specifiche.

Feature 3: Eseguire la ricerca e processare i risultati

Perché questo passaggio è importante

Trovare i barcode è solo metà della storia—devi agire sui dati (ad es. convalidare, memorizzare o avviare workflow).

Ancoraggio della definizione

BarcodeSignature rappresenta un barcode rilevato e contiene le sue proprietà come numero di pagina e testo decodificato.

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);
}

Ora disponi di un elenco di oggetti BarcodeSignature, ciascuno espone:

• getPageNumber() – dove si trova il barcode
• getEncodeType() – tipo di codifica (QR, Code128, ecc.)
• getText() – payload decodificato
• Posizione (getLeft(), getTop()) e dimensione (getWidth(), getHeight())

Esempio: Processare solo QR code nell’ultima pagina

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

Applicazioni reali

Problema 1 – Nessun risultato nonostante i barcode visibili

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

Se il barcode è incorporato come immagine raster, considera l’uso di GroupDocs.Image per il rilevamento basato su immagine.

Problema 2 – Prestazioni lente su file di grandi dimensioni

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

Le pagine mirate riducono drasticamente il tempo di elaborazione; un PDF di 150 pagine passa da ~4 secondi a <1 secondo quando limiti la ricerca a due pagine.

Problema 3 – TextMatchType non trova i barcode attesi

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

Problema 4 – Perdite di memoria in loop a lunga durata

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

Il blocco try‑with‑resources elimina automaticamente l’istanza Signature.

Best Practices per la produzione

Gestione robusta degli errori

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);
}

Cache dei risultati quando i documenti sono immutabili

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

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

Usa eventi di progresso per il feedback UI

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

Convalida i payload dei barcode

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);
    }
}

Ottimizza la selezione delle pagine per tipo di documento

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

Filtra per tipo di barcode dopo la ricerca (se ti servono solo QR code)

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

Estrai le dimensioni dell’immagine del barcode (se necessario per il rendering)

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

Domande frequenti

Q: Posso cercare più formati di barcode in una singola chiamata?
A: Sì. BarcodeSearchOptions ricerca tutti i formati supportati per impostazione predefinita. Filtra i risultati con getEncodeType() se ti servono solo tipi specifici.

Q: Come gestisco documenti che contengono sia barcode sia firme immagine?
A: Esegui ricerche separate—usa BarcodeSignature.class per i barcode e ImageSignature.class per le firme immagine, poi combina i risultati secondo necessità.

Q: Qual è l’impatto sulle prestazioni della ricerca su tutte le pagine rispetto a pagine specifiche?
A: Scansionare ogni pagina di un PDF di 50 pagine può richiedere 3–5 secondi. Limitare la ricerca alle prime + ultime pagine di solito termina in meno di 1 secondo.

Q: Funziona con PDF scansionati (immagini raster)?
A: Solo se il barcode è stato aggiunto come oggetto di firma digitale. Per barcode presenti solo come raster, è necessario un riconoscitore basato su immagine (ad es. GroupDocs.Barcode).

Q: Come posso verificare che una firma barcode non sia stata manomessa?
A: Inserisci un hash o una firma digitale all’interno del payload del barcode, quindi ricalcola l’hash sui dati originali e confrontalo. Questo richiede la chiave di firma o il certificato originale.

Ultimo aggiornamento: 2026-06-21
Testato con: GroupDocs.Signature 23.12 for Java
Autore: GroupDocs

Tutorial correlati

• How to Add Barcode to PDF Java with GroupDocs.Signature
• How to Verify Barcode Signatures in Java with GroupDocs.Signature
• GroupDocs Signature Java Event Subscription - Track Verification in Real-Time