Skip to content

Commit 3fe2a05

Browse files
author
Aleksander Grinin
committed
Add articles to /java/developer-guide/complex-barcode/ section
1 parent 3fe6c91 commit 3fe2a05

15 files changed

Lines changed: 1057 additions & 3 deletions

File tree

‎java/developer-guide/barcode-generation/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "Barcode Generation"
33
description: "Generate and configure barcodes with Aspose.BarCode for Java."
44
type: docs
5-
weight: 1
5+
weight: 30
66
url: /java/developer-guide/barcode-generation/
77
---
88

‎java/developer-guide/barcode-recognition/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Barcode Recognition
33
type: docs
4-
weight: 10
4+
weight: 20
55
url: /java/developer-guide/barcode-recognition
66
---

‎java/developer-guide/complex-barcode/_index.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: "Complex Barcode"
3+
description: "Learn how to generate, read, decode, and troubleshoot structured complex barcodes with Aspose.BarCode for Java."
4+
type: docs
5+
weight: 40
6+
url: /java/developer-guide/complex-barcode/
7+
---
8+
9+
# Complex Barcode
10+
11+
Complex barcodes encode structured business data defined by payment, postal, healthcare, shipping, and identification standards.
12+
13+
Aspose.BarCode for Java provides typed complex codetext classes for creating standard-compliant payloads, generating their carrier barcodes, recognizing barcode images, and decoding recognized text back into structured Java objects.
14+
15+
This section contains the following articles:
16+
17+
- [Introduction to Complex Barcodes](introduction/)
18+
- [Generate Complex Barcodes](generate/)
19+
- [Read Complex Barcodes](read/)
20+
- [Complete Complex Barcode Examples](examples/)
21+
- [Swiss QR Barcodes](supported_types/swiss_qr/)
22+
- [HIBC Barcodes](supported_types/hibc/)
23+
- [Royal Mail Mailmark Barcodes](supported_types/royal_mail_mailmark/)
24+
- [MaxiCode Barcodes](supported_types/maxicode/)
25+
- [USA Driver ID Barcodes](supported_types/usa_driver_id/)
26+
- [Troubleshoot Complex Barcodes](troubleshooting/)

‎java/developer-guide/complex-barcode/examples/_index.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: "Complete Complex Barcode Examples"
3+
description: "Explore complete end-to-end workflows for generating, recognizing, decoding, and validating complex barcodes."
4+
type: docs
5+
weight: 40
6+
url: /java/developer-guide/complex-barcode/examples/
7+
---
8+
9+
# Complete Complex Barcode Examples
10+
11+
Complete workflows combine typed data creation, image generation, recognition, complex decoding, and field-by-field validation.
12+
13+
The complete source code for this article is available on GitHub:
14+
15+
<a href="https://github.com/aspose-barcode/Aspose.BarCode-for-Java/blob/master/src/test/java/com/aspose/barcode/guide/complex/examples/CompleteComplexBarcodeExamples.java" target="_blank">View CompleteComplexBarcodeExamples.java</a>
16+
17+
## Generate, read, and decode Swiss QR
18+
19+
```java
20+
SwissQRCodetext sourceCodetext =
21+
createSwissQRCodetext();
22+
23+
ComplexBarcodeGenerator generator =
24+
new ComplexBarcodeGenerator(sourceCodetext);
25+
26+
generator.save(outputPath, BarCodeImageFormat.PNG);
27+
```
28+
29+
Recognize and decode the result:
30+
31+
```java
32+
BarCodeReader reader =
33+
new BarCodeReader(outputPath, DecodeType.QR);
34+
35+
BarCodeResult[] results = reader.readBarCodes();
36+
37+
SwissQRCodetext decoded =
38+
ComplexCodetextReader.tryDecodeSwissQR(
39+
results[0].getCodeText()
40+
);
41+
```
42+
43+
## Process multiple complex barcodes
44+
45+
The example places a Swiss QR symbol and an HIBC QR LIC symbol into one composite image.
46+
47+
```java
48+
BufferedImage swissImage =
49+
new ComplexBarcodeGenerator(
50+
swissCodetext
51+
).generateBarCodeImage();
52+
53+
BufferedImage hibcImage =
54+
new ComplexBarcodeGenerator(
55+
hibcCodetext
56+
).generateBarCodeImage();
57+
```
58+
59+
Read all supported carrier types and route each result to the corresponding complex decoder.
60+
61+
## Verify round-trip business data
62+
63+
A strong regression test compares typed fields after decoding:
64+
65+
```java
66+
Assert.assertEquals(
67+
decodedCodetext.getPrimaryData(),
68+
sourceCodetext.getPrimaryData()
69+
);
70+
71+
Assert.assertEquals(
72+
decodedCodetext.getSecondaryAndAdditionalData(),
73+
sourceCodetext.getSecondaryAndAdditionalData()
74+
);
75+
```
76+
77+
This detects data loss that a simple recognition check might miss.
78+
79+
## Use end-to-end tests
80+
81+
Complete tests can detect:
82+
83+
- missing required fields;
84+
- serialization errors;
85+
- image generation regressions;
86+
- carrier recognition regressions;
87+
- complex parsing regressions;
88+
- field conversion errors.
89+
90+
## Recommendations
91+
92+
- Validate both recognition and structured decoding.
93+
- Compare business fields, not only raw codetext.
94+
- Test documents that contain several complex barcodes.
95+
- Route each carrier to the appropriate decoder.
96+
- Keep representative end-to-end cases in automated tests.

‎java/developer-guide/complex-barcode/generate/_index.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: "Generate Complex Barcodes"
3+
description: "Learn how to create structured complex barcode data, generate images, configure appearance, and save output to files or streams."
4+
type: docs
5+
weight: 20
6+
url: /java/developer-guide/complex-barcode/generate/
7+
---
8+
9+
# Generate Complex Barcodes
10+
11+
Complex barcode generation starts with a typed business object. The model validates and constructs the standardized payload before the barcode image is created.
12+
13+
The complete source code for this article is available on GitHub:
14+
15+
<a href="https://github.com/aspose-barcode/Aspose.BarCode-for-Java/blob/master/src/test/java/com/aspose/barcode/guide/complex/generate/GenerateComplexBarcodes.java" target="_blank">View GenerateComplexBarcodes.java</a>
16+
17+
## Create structured HIBC LIC data
18+
19+
HIBC LIC separates primary product identification from secondary production data:
20+
21+
```java
22+
HIBCLICCombinedCodetext codetext =
23+
new HIBCLICCombinedCodetext();
24+
25+
codetext.setBarcodeType(EncodeTypes.HIBCQRLIC);
26+
27+
PrimaryData primaryData = new PrimaryData();
28+
primaryData.setLabelerIdentificationCode("A999");
29+
primaryData.setProductOrCatalogNumber("12345");
30+
primaryData.setUnitOfMeasureID(1);
31+
codetext.setPrimaryData(primaryData);
32+
```
33+
34+
Add expiry date, quantity, lot number, serial number, and manufacture date through `SecondaryAndAdditionalData`.
35+
36+
## Generate a complex barcode image
37+
38+
```java
39+
SwissQRCodetext codetext = createSwissQRCodetext();
40+
41+
ComplexBarcodeGenerator generator =
42+
new ComplexBarcodeGenerator(codetext);
43+
44+
generator.save(
45+
"generated_swiss_qr.png",
46+
BarCodeImageFormat.PNG
47+
);
48+
```
49+
50+
The generator obtains the final payload and carrier type from the complex codetext object.
51+
52+
## Configure appearance
53+
54+
Complex generators expose common generation parameters:
55+
56+
```java
57+
generator.getParameters()
58+
.setBackColor(new Color(245, 248, 252));
59+
60+
generator.getParameters()
61+
.getBarcode()
62+
.setBarColor(new Color(20, 45, 90));
63+
64+
generator.getParameters()
65+
.getBarcode()
66+
.getXDimension()
67+
.setPixels(3);
68+
```
69+
70+
Padding and borders can be configured in the same way as for regular barcode generation. These settings do not modify the business data.
71+
72+
## Save to a stream
73+
74+
```java
75+
ByteArrayOutputStream outputStream =
76+
new ByteArrayOutputStream();
77+
78+
generator.save(
79+
outputStream,
80+
BarCodeImageFormat.PNG
81+
);
82+
83+
byte[] imageBytes = outputStream.toByteArray();
84+
```
85+
86+
Stream output is useful for web responses, cloud storage, document composition, and database workflows.
87+
88+
## Verify generated output
89+
90+
Recognize the generated image and compare its payload with `getConstructedCodetext()`:
91+
92+
```java
93+
assertImageHasBarcodes(
94+
outputPath,
95+
1,
96+
List.of(
97+
expected(
98+
DecodeType.QR,
99+
codetext.getConstructedCodetext()
100+
)
101+
)
102+
);
103+
```
104+
105+
For critical workflows, decode the recognized text back into the typed model and compare business fields.
106+
107+
## Recommendations
108+
109+
- Build the typed model before creating the generator.
110+
- Validate required fields before saving.
111+
- Keep appearance configuration separate from business data.
112+
- Use streams when intermediate files are unnecessary.
113+
- Verify generated output through recognition and structured decoding.

‎java/developer-guide/complex-barcode/introduction/_index.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: "Introduction to Complex Barcodes"
3+
description: "Learn how complex barcodes use typed business data models, carrier symbologies, and structured decoding workflows in Aspose.BarCode for Java."
4+
type: docs
5+
weight: 10
6+
url: /java/developer-guide/complex-barcode/introduction/
7+
---
8+
9+
# Introduction to Complex Barcodes
10+
11+
Complex barcodes represent structured business data through dedicated Java classes instead of requiring applications to assemble the final encoded text manually.
12+
13+
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.
14+
15+
The complete source code for this article is available on GitHub:
16+
17+
<a href="https://github.com/aspose-barcode/Aspose.BarCode-for-Java/blob/master/src/test/java/com/aspose/barcode/guide/complex/introduction/ComplexBarcodeIntroduction.java" target="_blank">View ComplexBarcodeIntroduction.java</a>
18+
19+
## Regular and complex barcode generation
20+
21+
A regular `BarcodeGenerator` receives the final payload directly:
22+
23+
```java
24+
BarcodeGenerator generator = new BarcodeGenerator(
25+
EncodeTypes.QR,
26+
constructedCodetext
27+
);
28+
```
29+
30+
A `ComplexBarcodeGenerator` receives an implementation of `IComplexCodetext`:
31+
32+
```java
33+
SwissQRCodetext codetext = new SwissQRCodetext();
34+
35+
ComplexBarcodeGenerator generator =
36+
new ComplexBarcodeGenerator(codetext);
37+
```
38+
39+
The complex codetext object constructs the standard-specific payload and selects the appropriate carrier symbology.
40+
41+
## Create typed business data
42+
43+
The following example initializes a Swiss QR payment model:
44+
45+
```java
46+
SwissQRCodetext codetext = new SwissQRCodetext();
47+
48+
codetext.getBill().setVersion(QrBillStandardVersion.V2_0);
49+
codetext.getBill().setAccount("CH4431999123000889012");
50+
codetext.getBill().setAmount(100.25);
51+
codetext.getBill().setCurrency("CHF");
52+
```
53+
54+
The model exposes payment fields such as account, amount, currency, creditor, debtor, reference, and message.
55+
56+
## Supported complex barcode models
57+
58+
Aspose.BarCode for Java provides typed classes for Swiss QR, HIBC LIC, HIBC PAS, Royal Mail Mailmark, MaxiCode, and USA Driver ID.
59+
60+
The supported classes include:
61+
62+
- `SwissQRCodetext`;
63+
- `HIBCLICCombinedCodetext`;
64+
- `HIBCPASCodetext`;
65+
- `MailmarkCodetext`;
66+
- `Mailmark2DCodetext`;
67+
- `MaxiCodeCodetextMode2`;
68+
- `MaxiCodeCodetextMode3`;
69+
- `USADriveIdCodetext`.
70+
71+
## Understand the carrier symbology
72+
73+
A complex barcode still uses a regular physical barcode type. For example:
74+
75+
- Swiss QR uses QR Code;
76+
- Mailmark 2D uses Data Matrix;
77+
- USA Driver ID uses PDF417;
78+
- MaxiCode business data uses MaxiCode.
79+
80+
The carrier is recognized first. Its text is then passed to a complex codetext decoder.
81+
82+
## Complete processing workflow
83+
84+
```java
85+
ComplexBarcodeGenerator generator =
86+
new ComplexBarcodeGenerator(sourceCodetext);
87+
88+
generator.save(outputPath, BarCodeImageFormat.PNG);
89+
90+
BarCodeReader reader =
91+
new BarCodeReader(outputPath, DecodeType.QR);
92+
93+
BarCodeResult[] results = reader.readBarCodes();
94+
95+
SwissQRCodetext decodedCodetext =
96+
ComplexCodetextReader.tryDecodeSwissQR(
97+
results[0].getCodeText()
98+
);
99+
```
100+
101+
The workflow consists of creating a typed model, generating the carrier image, recognizing the carrier, and decoding its standardized text into a typed object.
102+
103+
## Recommendations
104+
105+
- Populate all required business fields before generation.
106+
- Recognize the underlying carrier before complex decoding.
107+
- Use the decoder that matches the expected complex standard.
108+
- Validate decoded fields instead of checking only the raw text.
109+
- Apply a valid license before generation and recognition tests.

0 commit comments

Comments
 (0)