Complex Barcode API Overview

Complex Barcode API Overview

Aspose.BarCode for Java provides a small set of API classes for working with complex barcodes. These classes separate structured business data, barcode generation, barcode recognition, and complex codetext decoding.

The complete source code for this article is available on GitHub:

View ComplexBarcodeApiOverview.java

Main API classes

The complex barcode workflow usually involves the following classes:

API class Responsibility
IComplexCodetext Common interface for complex codetext models.
SwissQRCodetext, HIBCLICCombinedCodetext, HIBCPASCodetext, MailmarkCodetext, Mailmark2DCodetext, MaxiCodeCodetextMode2, USADriveIdCodetext Typed models for supported complex barcode standards.
ComplexBarcodeGenerator Generates a barcode image from a typed complex codetext object.
BarcodeGenerator Generates a barcode image from already prepared plain text.
BarCodeReader Recognizes the physical barcode symbology from an image.
BarCodeResult Represents a recognized barcode and its decoded text.
ComplexCodetextReader Converts recognized barcode text back into a typed complex codetext object.

API workflow

A complex barcode is generated from a typed business object. During reading, the barcode image is recognized first, and the recognized text is then decoded as a complex codetext.

Generation

Typed complex codetext
        |
        v
ComplexBarcodeGenerator
        |
        v
Barcode image

Recognition and decoding

Barcode image
        |
        v
BarCodeReader
        |
        v
BarCodeResult
        |
        v
ComplexCodetextReader
        |
        v
Typed complex codetext

Typed complex codetext models

Complex barcode generation starts from a typed model. For example, Swiss QR payment data is represented by SwissQRCodetext:

SwissQRCodetext codetext = new SwissQRCodetext();

codetext.getBill().setVersion(QrBillStandardVersion.V2_0);
codetext.getBill().setAccount("CH4431999123000889012");
codetext.getBill().setAmount(100.25);
codetext.getBill().setCurrency("CHF");

The model stores business fields and constructs the standard-specific payload internally:

String constructedCodetext = codetext.getConstructedCodetext();

For Swiss QR, the physical barcode symbology is QR Code:

Assert.assertEquals(codetext.getBarcodeType(), EncodeTypes.QR);

BarcodeGenerator and ComplexBarcodeGenerator

BarcodeGenerator is the general-purpose generator. It receives the exact text that must be encoded:

BarcodeGenerator regularGenerator =
        new BarcodeGenerator(EncodeTypes.QR, constructedCodetext);

ComplexBarcodeGenerator receives a typed complex codetext object:

ComplexBarcodeGenerator complexGenerator =
        new ComplexBarcodeGenerator(codetext);

Use BarcodeGenerator when the application already has the final text payload. Use ComplexBarcodeGenerator when the application works with a supported structured standard, such as Swiss QR, HIBC, Royal Mail Mailmark, MaxiCode, or USA Driver ID.

Recognition and complex decoding

Reading complex barcodes is a two-stage process.

First, recognize the physical barcode image:

BarCodeReader reader = new BarCodeReader(imagePath, DecodeType.QR);
BarCodeResult[] results = reader.readBarCodes();

Then decode the recognized text as a complex codetext:

SwissQRCodetext decodedCodetext =
        ComplexCodetextReader.tryDecodeSwissQR(results[0].getCodeText());

BarCodeReader does not return SwissQRCodetext directly. It returns BarCodeResult objects. The complex codetext decoder is applied after recognition.

Standard-specific decoding

Complex decoding must match the expected standard. A plain QR Code can be recognized successfully as QR, but it is not automatically a Swiss QR payment barcode:

BarcodeGenerator generator = new BarcodeGenerator(EncodeTypes.QR, "Plain QR text");
generator.save(plainQrPath, BarCodeImageFormat.PNG);

BarCodeReader reader = new BarCodeReader(plainQrPath, DecodeType.QR);
BarCodeResult[] results = reader.readBarCodes();

Assert.assertEquals(results[0].getCodeText(), "Plain QR text");
Assert.assertNull(ComplexCodetextReader.tryDecodeSwissQR(results[0].getCodeText()));

This separation is intentional: recognition detects the barcode symbology and extracts text, while complex decoding interprets that text according to a specific business standard.

Recommendations

  • Use typed complex codetext classes instead of manually assembling standard-specific payloads.
  • Use ComplexBarcodeGenerator when generating supported complex barcode standards.
  • Use BarCodeReader to recognize the physical barcode first.
  • Use the matching method from ComplexCodetextReader to decode the recognized text.
  • Validate important business fields after decoding, not only the raw barcode text.
Concepts