Documentation – Complex Barcode

Java: Introduction to Complex Barcodes

Mon, 01 Jan 0001 00:00:00 +0000

Introduction to Complex Barcodes

Complex barcodes represent structured business data through dedicated Java classes instead of requiring applications to assemble the final encoded text manually.

Aspose.BarCode for Java separates the business model, the physical carrier symbology, and the decoding step. This approach reduces formatting errors and makes decoded fields available through typed Java objects.

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

View ComplexBarcodeIntroduction.java

Regular and complex barcode generation

A regular BarcodeGenerator receives the final payload directly:

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

A ComplexBarcodeGenerator receives an implementation of IComplexCodetext:

SwissQRCodetext codetext = new SwissQRCodetext();

ComplexBarcodeGenerator generator =
        new ComplexBarcodeGenerator(codetext);

The complex codetext object constructs the standard-specific payload and selects the appropriate carrier symbology.

Create typed business data

The following example initializes a Swiss QR payment model:

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 exposes payment fields such as account, amount, currency, creditor, debtor, reference, and message.

Supported complex barcode models

Aspose.BarCode for Java provides typed classes for Swiss QR, HIBC LIC, HIBC PAS, Royal Mail Mailmark, MaxiCode, and USA Driver ID.

The supported classes include:

SwissQRCodetext;
HIBCLICCombinedCodetext;
HIBCPASCodetext;
MailmarkCodetext;
Mailmark2DCodetext;
MaxiCodeCodetextMode2;
MaxiCodeCodetextMode3;
USADriveIdCodetext.

Understand the carrier symbology

A complex barcode still uses a regular physical barcode type. For example:

Swiss QR uses QR Code;
Mailmark 2D uses Data Matrix;
USA Driver ID uses PDF417;
MaxiCode business data uses MaxiCode.

The carrier is recognized first. Its text is then passed to a complex codetext decoder.

Complete processing workflow

ComplexBarcodeGenerator generator =
        new ComplexBarcodeGenerator(sourceCodetext);

generator.save(outputPath, BarCodeImageFormat.PNG);

BarCodeReader reader =
        new BarCodeReader(outputPath, DecodeType.QR);

BarCodeResult[] results = reader.readBarCodes();

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

The workflow consists of creating a typed model, generating the carrier image, recognizing the carrier, and decoding its standardized text into a typed object.

Recommendations

Populate all required business fields before generation.
Recognize the underlying carrier before complex decoding.
Use the decoder that matches the expected complex standard.
Validate decoded fields instead of checking only the raw text.
Apply a valid license before generation and recognition tests.

Java: Generate Complex Barcodes

Mon, 01 Jan 0001 00:00:00 +0000

Generate Complex Barcodes

Complex barcode generation starts with a typed business object. The model validates and constructs the standardized payload before the barcode image is created.

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

View GenerateComplexBarcodes.java

Create structured HIBC LIC data

HIBC LIC separates primary product identification from secondary production data:

HIBCLICCombinedCodetext codetext =
        new HIBCLICCombinedCodetext();

codetext.setBarcodeType(EncodeTypes.HIBCQRLIC);

PrimaryData primaryData = new PrimaryData();
primaryData.setLabelerIdentificationCode("A999");
primaryData.setProductOrCatalogNumber("12345");
primaryData.setUnitOfMeasureID(1);
codetext.setPrimaryData(primaryData);

Add expiry date, quantity, lot number, serial number, and manufacture date through SecondaryAndAdditionalData.

SecondaryAndAdditionalData secondaryData =
        new SecondaryAndAdditionalData();

secondaryData.setExpiryDateFormat(
        HIBCLICDateFormat.YYYYMMDD
);

secondaryData.setExpiryDate(
        LocalDateTime.of(2027, 12, 31, 0, 0)
);

secondaryData.setQuantity(30);
secondaryData.setLotNumber("LOT123");
secondaryData.setSerialNumber("SERIAL123");
secondaryData.setDateOfManufacture(
        LocalDateTime.of(2026, 1, 15, 0, 0)
);

codetext.setSecondaryAndAdditionalData(
        secondaryData
);

The model constructs the standard-compliant HIBC LIC payload automatically.

Generate a complex barcode image

SwissQRCodetext codetext = createSwissQRCodetext();

ComplexBarcodeGenerator generator =
        new ComplexBarcodeGenerator(codetext);

generator.save(
        "generated_swiss_qr.png",
        BarCodeImageFormat.PNG
);

The generator obtains the final payload and carrier type from the complex codetext object.

Configure appearance

Complex generators expose common generation parameters:

generator.getParameters()
        .setBackColor(new Color(245, 248, 252));

generator.getParameters()
        .getBarcode()
        .setBarColor(new Color(20, 45, 90));

generator.getParameters()
        .getBarcode()
        .getXDimension()
        .setPixels(3);

Padding and borders can be configured in the same way as for regular barcode generation.

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getLeft()
        .setPixels(12);

generator.getParameters()
        .getBarcode()
        .getPadding()
        .getRight()
        .setPixels(12);

generator.getParameters()
        .getBorder()
        .setVisible(true);

generator.getParameters()
        .getBorder()
        .setColor(Color.GRAY);

generator.getParameters()
        .getBorder()
        .getWidth()
        .setPixels(2);

These settings affect only the generated image and do not modify the structured business data.

Save to a stream

ByteArrayOutputStream outputStream =
        new ByteArrayOutputStream();

generator.save(
        outputStream,
        BarCodeImageFormat.PNG
);

byte[] imageBytes = outputStream.toByteArray();

Stream output is useful for web responses, cloud storage, document composition, and database workflows.

Verify generated output

Use BarCodeReader to recognize the generated carrier barcode and compare the recognized payload with getConstructedCodetext().

BarCodeReader reader = new BarCodeReader(
        "generated_swiss_qr.png",
        DecodeType.QR
);

BarCodeResult[] results =
        reader.readBarCodes();

if (results.length != 1) {
    throw new IllegalStateException(
            "Expected exactly one QR barcode."
    );
}

if (!results[0].getCodeType().equals(
        DecodeType.QR
)) {
    throw new IllegalStateException(
            "Unexpected barcode type: "
                    + results[0].getCodeType()
    );
}

if (!results[0].getCodeText().equals(
        codetext.getConstructedCodetext()
)) {
    throw new IllegalStateException(
            "Recognized payload does not match "
                    + "the constructed codetext."
    );
}

This example uses only the public Aspose.BarCode API.

For critical workflows, decode the recognized text back into the typed model and compare business fields.

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

if (decodedCodetext == null) {
    throw new IllegalStateException(
            "The recognized payload could not be "
                    + "decoded as Swiss QR."
    );
}

if (!decodedCodetext.getBill()
        .getAccount()
        .equals(codetext.getBill().getAccount())) {
    throw new IllegalStateException(
            "Decoded account does not match "
                    + "the source data."
    );
}

Recommendations

Build the typed model before creating the generator.
Validate required fields before saving.
Keep appearance configuration separate from business data.
Use streams when intermediate files are unnecessary.
Recognize the generated carrier with BarCodeReader.
Decode the recognized text with the matching complex codetext reader.
Compare important business fields after decoding.

Java: Read Complex Barcodes

Mon, 01 Jan 0001 00:00:00 +0000

Read Complex Barcodes

Reading a complex barcode is a two-stage operation. First, recognize the physical carrier symbology. Then pass the recognized text to the appropriate complex codetext decoder.

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

View ReadComplexBarcodes.java

Recognize the carrier barcode

BarCodeReader reader = new BarCodeReader(
        outputPath,
        DecodeType.QR
);

BarCodeResult[] results = reader.readBarCodes();

For Swiss QR, the reader reports DecodeType.QR. At this stage, the result contains the standardized text but not yet the typed payment model.

Decode the recognized text

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

For HIBC LIC:

HIBCLICComplexCodetext decodedBase =
        ComplexCodetextReader.tryDecodeHIBCLIC(
                results[0].getCodeText()
        );

Check the returned subtype before accessing format-specific fields.

Access business fields

After decoding, application code can access typed properties:

String account =
        decodedCodetext.getBill().getAccount();

double amount =
        decodedCodetext.getBill().getAmount();

String creditorName =
        decodedCodetext.getBill()
                .getCreditor()
                .getName();

Handle unsupported text

The tryDecode... methods return null when text does not conform to the requested format:

String unsupported =
        "NOT-A-SUPPORTED-COMPLEX-BARCODE";

Assert.assertNull(
        ComplexCodetextReader.tryDecodeSwissQR(
                unsupported
        )
);

This allows an application to try another decoder or report unsupported content without interrupting the workflow.

Choose the correct decoder

Use the method that matches the expected standard:

tryDecodeSwissQR;
tryDecodeHIBCLIC;
tryDecodeHIBCPAS;
tryDecodeMailmark;
tryDecodeMailmark2D;
tryDecodeMaxiCode;
tryDecodeUSADriveId.

The carrier type alone may not uniquely identify the business format.

Recommendations

Check the number of recognition results before accessing them.
Confirm the carrier DecodeType.
Pass recognized text to the matching complex decoder.
Handle null results from tryDecode... methods.
Validate important business fields after decoding.
Keep recognition failures separate from parsing failures.

Java: Supported Complex Barcode Types

Mon, 01 Jan 0001 00:00:00 +0000

Supported Complex Barcode Types

Aspose.BarCode for Java provides typed APIs for several complex barcode standards used in payment, healthcare, postal, shipping, and identification workflows.

Each article in this section explains how to create the corresponding structured data model, generate its carrier barcode, recognize the image, and decode the payload back into a typed Java object.

This section contains the following articles:

Swiss QR Barcodes — generate Swiss QR Bills and decode structured payment data.
HIBC Barcodes — work with HIBC LIC product data and HIBC PAS healthcare records.
Royal Mail Mailmark Barcodes — generate and read Mailmark 1D and Mailmark 2D postal barcodes.
MaxiCode Barcodes — create and decode structured MaxiCode mode 2 and mode 3 payloads.
USA Driver ID Barcodes — generate and read AAMVA driver-license data stored in PDF417.

Java: Complete Complex Barcode Examples

Mon, 01 Jan 0001 00:00:00 +0000

Complete Complex Barcode Examples

Complete workflows combine typed data creation, image generation, recognition, complex decoding, and field-by-field validation.

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

View CompleteComplexBarcodeExamples.java

Generate, read, and decode Swiss QR

SwissQRCodetext sourceCodetext =
        createSwissQRCodetext();

ComplexBarcodeGenerator generator =
        new ComplexBarcodeGenerator(sourceCodetext);

generator.save(outputPath, BarCodeImageFormat.PNG);

Recognize and decode the result:

BarCodeReader reader =
        new BarCodeReader(outputPath, DecodeType.QR);

BarCodeResult[] results = reader.readBarCodes();

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

Process multiple complex barcodes

The example places a Swiss QR symbol and an HIBC QR LIC symbol into one composite image.

BufferedImage swissImage =
        new ComplexBarcodeGenerator(
                swissCodetext
        ).generateBarCodeImage();

BufferedImage hibcImage =
        new ComplexBarcodeGenerator(
                hibcCodetext
        ).generateBarCodeImage();

Read all supported carrier types and route each result to the corresponding complex decoder.

Verify round-trip business data

A strong regression test compares typed fields after decoding:

Assert.assertEquals(
        decodedCodetext.getPrimaryData(),
        sourceCodetext.getPrimaryData()
);

Assert.assertEquals(
        decodedCodetext.getSecondaryAndAdditionalData(),
        sourceCodetext.getSecondaryAndAdditionalData()
);

This detects data loss that a simple recognition check might miss.

Use end-to-end tests

Complete tests can detect:

missing required fields;
serialization errors;
image generation regressions;
carrier recognition regressions;
complex parsing regressions;
field conversion errors.

Recommendations

Validate both recognition and structured decoding.
Compare business fields, not only raw codetext.
Test documents that contain several complex barcodes.
Route each carrier to the appropriate decoder.
Keep representative end-to-end cases in automated tests.

Java: Troubleshoot Complex Barcodes

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshoot Complex Barcodes

Complex barcode problems can occur at different stages: image recognition, standardized text decoding, required-field validation, or standard-specific range validation. Diagnosing the correct stage avoids misleading fixes.

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

View ComplexBarcodeTroubleshooting.java

Barcode image is not recognized

A blank or damaged image produces no results:

BarCodeReader reader = new BarCodeReader(
        outputPath,
        DecodeType.ALL_SUPPORTED_TYPES
);

BarCodeResult[] results =
        reader.readBarCodes();

Assert.assertEquals(results.length, 0);

This is an image-recognition problem rather than a complex codetext problem. Check image quality, contrast, quiet zones, scaling, and the selected carrier type.

Recognized text cannot be decoded

A carrier can be recognized while its text is invalid for the requested complex format:

String invalidCodetext =
        "NOT-A-COMPLEX-BARCODE";

Assert.assertNull(
        ComplexCodetextReader.tryDecodeSwissQR(
                invalidCodetext
        )
);

The tryDecode... methods return null for unsupported data.

Required fields are missing

Constructing codetext can raise BarCodeException when required data is absent:

SwissQRCodetext incomplete =
        new SwissQRCodetext();

try {
    incomplete.getConstructedCodetext();
} catch (BarCodeException exception) {
    // Inspect the validation message.
}

For Swiss QR, a missing or invalid IBAN is one possible cause.

Data violates a standard limit

The API validates standard-specific ranges before generation:

MailmarkCodetext invalid =
        new MailmarkCodetext();

invalid.setItemID(100_000_000);

An out-of-range Mailmark item identifier causes BarCodeException during codetext construction.

Use a staged diagnostic workflow

Check failures in this order:

verify that the image exists and is readable;
recognize the carrier barcode;
confirm the recognized DecodeType;
inspect the recognized text;
call the matching complex decoder;
validate required decoded fields.

Recommendations

Do not treat an empty recognition result as a decoding failure.
Check for null from tryDecode... methods.
Validate required fields before generation.
Catch BarCodeException around codetext construction.
Include standard-limit cases in automated tests.
Log carrier type and recognized text when diagnosing failures.