Documentation – Concepts

Java: Using ComplexBarcodeGenerator

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

BarcodeGenerator vs ComplexBarcodeGenerator

Aspose.BarCode for Java provides two generation workflows:

BarcodeGenerator creates a barcode from a barcode symbology and ready-to-encode text.
ComplexBarcodeGenerator creates a barcode from a typed complex codetext object.

Use BarcodeGenerator when the application already has the exact text that must be encoded. Use ComplexBarcodeGenerator when the application works with a supported Complex Barcode standard, such as Swiss QR, HIBC, Royal Mail Mailmark, MaxiCode, or USA Driver ID.

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

View ComplexBarcodeGeneratorExample.java

Regular barcode generation

BarcodeGenerator is the general-purpose barcode generation API. It receives the target symbology and the exact text to encode.

String codeText = "Plain application text";

BarcodeGenerator generator = new BarcodeGenerator(EncodeTypes.QR, codeText);
generator.save(outputPath, BarCodeImageFormat.PNG);

This is the right choice when the barcode stores application-defined text, identifiers, URLs, or other data that does not need a dedicated Complex Barcode model.

The generator does not interpret the text as Swiss QR, HIBC, Mailmark, MaxiCode, or another structured standard. It simply encodes the supplied text into the selected barcode symbology.

Complex Barcode generation

ComplexBarcodeGenerator works with typed codetext objects from the com.aspose.barcode.complexbarcode package.

For example, Swiss QR payment data is represented by SwissQRCodetext:

SwissQRCodetext codetext = new SwissQRCodetext();
codetext.getBill().setAccount("CH4431999123000889012");
codetext.getBill().setAmount(100.25);
codetext.getBill().setCurrency("CHF");

ComplexBarcodeGenerator generator = new ComplexBarcodeGenerator(codetext);
generator.save(outputPath, BarCodeImageFormat.PNG);

In this workflow, the application fills a structured Java object. Aspose.BarCode constructs the standardized payload and encodes it into the barcode symbology required by the Complex Barcode type.

Main difference

API	Input	Best used for
`BarcodeGenerator`	Ready-to-encode string	Plain barcodes and custom application data
`ComplexBarcodeGenerator`	Typed complex codetext object	Supported Complex Barcode standards

Both APIs can produce a barcode with the same encoded payload if the final standardized codetext is already known. However, only ComplexBarcodeGenerator lets the application work with a typed Complex Barcode object instead of manually building the standardized text.

Encoding an already constructed payload

A complex codetext object can expose the final standardized text:

String constructedCodetext = codetext.getConstructedCodetext();

This text can be encoded with the regular generator:

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

This produces a QR Code that contains the same payload. However, this approach bypasses the main benefit of the Complex Barcode API: building the payload from a typed object.

Recommended usage

Use BarcodeGenerator when:

the barcode content is already a final string;
the application uses a regular barcode symbology directly;
no Complex Barcode standard-specific model is needed.

Use ComplexBarcodeGenerator when:

the barcode represents a supported Complex Barcode standard;
the application should work with typed business fields;
the standardized payload should be constructed by Aspose.BarCode;
the encoded data may later need to be decoded back into a typed object.

Complete workflow

The example class demonstrates three cases:

generating a plain QR Code with BarcodeGenerator;
generating Swiss QR with ComplexBarcodeGenerator;
comparing the payload generated by both approaches.

The important distinction is not the visual barcode image. The important distinction is the data model used by the application before generation.

Java: Recognition vs Decoding

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

Recognition vs Decoding

Reading a Complex Barcode is a two-stage process:

Recognition reads the physical barcode symbol from an image.
Decoding interprets the recognized text as a specific Complex Barcode standard.

These two steps are intentionally separate. BarCodeReader recognizes barcode symbols and returns BarCodeResult objects. It does not directly return SwissQRCodetext, HIBCLICCombinedCodetext, MailmarkCodetext, or another typed Complex Barcode object.

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

View RecognitionVsDecoding.java

Recognition reads the barcode symbol

The first step is regular barcode recognition.

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

For Swiss QR, the recognized barcode type is still DecodeType.QR because Swiss QR is encoded as a QR Code symbol.

Assert.assertEquals(results[0].getCodeType(), DecodeType.QR);
Assert.assertEquals(results[0].getCodeText(), sourceCodetext.getConstructedCodetext());

At this stage, the result contains the standardized text, not a typed Swiss QR payment object.

Decoding restores the Complex Barcode object

The second step is Complex Barcode decoding.

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

After decoding, application code can access structured business fields:

String account = decodedCodetext.getBill().getAccount();
double amount = decodedCodetext.getBill().getAmount();
String creditorName = decodedCodetext.getBill().getCreditor().getName();

This is the point where the recognized barcode text becomes a typed Complex Barcode object.

Recognition can succeed while decoding fails

A QR Code can be valid as a barcode symbol but still not be a valid Swiss QR payload.

String plainText = "This is a valid QR Code, but not a Swiss QR payment.";
BarcodeGenerator generator = new BarcodeGenerator(EncodeTypes.QR, plainText);
generator.save(outputPath, BarCodeImageFormat.PNG);

Recognition succeeds:

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

Assert.assertEquals(results[0].getCodeType(), DecodeType.QR);
Assert.assertEquals(results[0].getCodeText(), plainText);

Swiss QR decoding fails because the text does not follow the Swiss QR payment format:

Assert.assertNull(
        ComplexCodetextReader.tryDecodeSwissQR(results[0].getCodeText())
);

This distinction is important for error handling. A failed recognition means the barcode symbol was not found or could not be read. A failed Complex Barcode decoding means the symbol was read, but its text does not match the requested structured format.

Processing model

Image
  |
  v
BarCodeReader
  |
  v
BarCodeResult
  |
  v
ComplexCodetextReader
  |
  v
Typed Complex Barcode object

For Swiss QR, this means:

QR Code image
  |
  v
BarCodeReader
  |
  v
BarCodeResult with DecodeType.QR and code text
  |
  v
ComplexCodetextReader.tryDecodeSwissQR(...)
  |
  v
SwissQRCodetext

Recommended usage

When reading Complex Barcode data:

first use BarCodeReader with the expected carrier symbology;
check that at least one BarCodeResult was returned;
check the recognized DecodeType when needed;
pass BarCodeResult.getCodeText() to the matching ComplexCodetextReader.tryDecode... method;
handle null from tryDecode... as a decoding failure, not as a recognition failure.