Cerca pagine specifiche con codici a barre 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 con codici a barre è noioso e soggetto a errori.

In questa guida ti mostreremo come cercare pagine specifiche con codici a barre nei tuoi documenti in modo programmatico con Java e GroupDocs.Signature. Alla fine, sarai in grado di rilevare le firme su pagine selezionate, monitorare l’avanzamento della ricerca in tempo reale e gestire una varietà di formati di codici a barre — il tutto con codice pulito e manutenibile.

Cosa imparerai

• 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

• Quale libreria ti aiuta a cercare pagine specifiche con codici a barre? GroupDocs.Signature per Java
• Tempo tipico di configurazione? Circa 5 minuti per aggiungere la dipendenza Maven/Gradle e una licenza
• Posso limitare la ricerca alla prima e all’ultima pagina? Sì – usa PagesSetup per specificare le pagine esatte
• Quali formati di codici a barre sono supportati? QR Code, Code128, Code39, DataMatrix, EAN/UPC e altri
• È necessaria una licenza a pagamento per la produzione? È necessaria una licenza completa per la produzione; una versione di prova è sufficiente per la valutazione

Cos’è “cerca pagine specifiche con codici a barre”?

Cercare pagine specifiche con codici a barre significa istruire il motore di firma a cercare le firme con codici a barre solo sulle pagine di tuo interesse — ad esempio la prima pagina, l’ultima pagina o qualsiasi intervallo personalizzato. Questo approccio mirato accelera l’elaborazione, riduce l’uso della memoria e consente di creare feedback UI reattivi.

Perché usare GroupDocs.Signature per questo compito?

GroupDocs.Signature fornisce un’API di alto livello che astrae la decodifica dei codici a barre a basso livello, il rendering delle pagine e la gestione dei formati dei documenti. Funziona con PDF, DOCX, XLSX e molti altri formati subito pronto all’uso, permettendoti di concentrarti sulla logica di business invece che 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 versione direttamente dalla pagina di download di GroupDocs.

Ottenere la tua licenza

• Prova gratuita – inizia subito, senza impegno
• Licenza temporanea – accesso completo alle funzionalità per la valutazione
• Licenza completa – pronta per la produzione, utilizzo illimitato

Verifica l’installazione con uno snippet di inizializzazione rapido:

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

Suggerimento professionale: 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 con codice a barre

I codici a barre incorporano dati leggibili da macchine all’interno di un documento. A differenza delle firme scritte a mano, possono memorizzare ID, timestamp, URL o payload JSON, rendendoli ideali per la verifica automatica.

Spesso utilizzerai i codici a barre quando hai bisogno di lettura rapida da macchina, dati strutturati o firme a prova di manomissione.

Come cercare pagine specifiche con codici a barre

Divideremo l’implementazione in tre funzionalità focalizzate.

Funzione 1: Iscriversi agli eventi di ricerca del documento

Perché è importante

Durante l’elaborazione di grandi lotti, il feedback in tempo reale (ad es. barre di avanzamento) migliora l’UX e aiuta a rilevare blocchi precocemente.

Implementazione

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 il logging o gli aggiornamenti UI.

Funzione 2: Configurare le opzioni di ricerca dei codici a barre 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 dell'80 %.

Implementazione

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

• Tipi di corrispondenza ti permettono di affinare la ricerca di testo (Contains, Exact, StartsWith, EndsWith).
• Regola setAllPages e PagesSetup per cercare solo pagine specifiche con codici a barre.

Funzione 3: Eseguire la ricerca e processare i risultati

Perché questo passaggio è importante

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

Implementazione

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 hai una lista di oggetti BarcodeSignature, ognuno dei quali espone:

• getPageNumber() – dove si trova il codice a barre
• getEncodeType() – QR, Code128, ecc.
• getText() – payload decodificato
• Posizione (getLeft(), getTop()) e dimensione (getWidth(), getHeight())

Esempio: Processa solo i codici QR sull’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 nel mondo reale

Problemi comuni e soluzioni

Problema 1 – Nessun risultato nonostante i codici a barre visibili

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

Se il codice a barre è 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.

Problema 3 – TextMatchType non trova i codici a barre attesi

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

Problema 4 – Perdite di memoria in cicli a lungo termine

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 practice 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 codici a barre

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 codice a barre dopo la ricerca (se ti servono solo i QR code)

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

Estrai le dimensioni dell’immagine del codice a barre (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

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

D: Come gestisco i documenti che contengono sia codici a barre sia firme immagine?
R: Esegui ricerche separate — usa BarcodeSignature.class per i codici a barre e ImageSignature.class per le firme immagine, quindi combina i risultati secondo necessità.

D: Qual è l’impatto sulle prestazioni della ricerca su tutte le pagine rispetto a pagine specifiche?
R: Scansionare ogni pagina di un PDF di 50 pagine può richiedere 3–5 secondi. Limitare alla prima + ultima pagina solitamente termina in meno di 1 secondo.

D: Funziona con PDF scansionati (immagini raster)?
R: Solo se il codice a barre è stato aggiunto come oggetto di firma digitale. Per codici a barre solo raster, è necessario un riconoscitore basato su immagine (ad es. GroupDocs.Barcode).

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

Ultimo aggiornamento: 2026-01-29
Testato con: GroupDocs.Signature 23.12 per Java
Autore: GroupDocs