This repository contains executable, self-documented TestNG examples for Aspose.BarCode for Java.
The examples demonstrate complete development workflows: configuring barcode data, generating barcode images, recognizing barcodes from different input sources, examining recognition results, validating decoded data, and working with structured complex barcode formats.
Each example is designed to accompany the official Aspose.BarCode for Java documentation and to provide code that can be run, inspected, and adapted for application development.
Use the following documentation sections together with the examples in this repository:
| Resource | Purpose |
|---|---|
| Aspose.BarCode for Java documentation | Main documentation entry point |
| Getting Started | Installation, licensing, system requirements, and initial setup |
| Developer Guide | Detailed generation, recognition, and complex barcode guides |
| API Reference | Java classes, methods, properties, and enumerations |
| Installation | Installing Aspose.BarCode for Java and configuring dependencies |
| Evaluation and Licensing | Applying a license and understanding evaluation limitations |
| Release Notes | Changes, fixes, and new features in each release |
Aspose.BarCode for Java supports Java 8 and later.
The examples in this repository require Java 17 or later to compile and run.
They may use Java APIs introduced after Java 8, including List.of(...) and
Path.of(...).
The repository is configured as a Gradle project and includes the Gradle wrapper. A separate local Gradle installation is not required.
The Java examples are organized under:
src/test/java/com/aspose/barcode/guide/
├── quickstart/
├── generation/
├── recognition/
├── complex/
└── common/
Sample input files and generated output files are stored under:
src/test/resources/
The main example areas are described below.
Directory:
src/test/java/com/aspose/barcode/guide/quickstart/
The quick start examples provide the shortest complete workflows for first-time users.
Demonstrates how to:
- create a
BarcodeGenerator; - select an encoding symbology;
- assign barcode text;
- generate a barcode image;
- save the result to a file;
- verify the generated barcode.
Related documentation:
Demonstrates how to:
- create a
BarCodeReader; - read a barcode image;
- select one or more
DecodeTypevalues; - iterate through
BarCodeResultobjects; - retrieve recognized text and barcode type.
Related documentation:
Directory:
src/test/java/com/aspose/barcode/guide/generation/
These examples explain how to create barcode images and configure their data, appearance, dimensions, output format, and validation behavior.
Main documentation section:
Directory:
generation/overview/
Provides introductory generation workflows and demonstrates the main steps used by the other generation examples:
- select an
EncodeTypesvalue; - provide codetext;
- configure generation parameters;
- generate or save the barcode image;
- recognize the result when verification is required.
Related documentation:
Directory:
generation/symbology_codetext/
Example classes include:
SetBarcodeSymbologyAndTextSymbologyAndCodeTextExample
These examples demonstrate how to:
- select a barcode symbology;
- assign and update codetext;
- use symbology-specific text formats;
- generate different barcode types from the same workflow;
- validate the recognized type and text.
Related documentation:
Directory:
generation/appearance/
Example classes include:
CustomizeBarcodeAppearanceCustomizeCaptionsAndText
These examples demonstrate high-level appearance configuration, including:
- foreground and background colors;
- barcode dimensions;
- text visibility;
- captions above and below the barcode;
- caption alignment, padding, and font settings.
Related documentation:
Directory:
generation/visual_parameters/
This is the most detailed set of visual-generation examples.
Example classes include:
BackgroundsExampleBordersExampleColorsExampleCustomizingCaptionsExampleCustomizingSizeExampleImageAndLayoutParametersExampleRotationExampleTextAndFontExampleUseUnitExampleVisualParametersAndLayout
The examples demonstrate how to configure:
- barcode and image colors;
- image backgrounds;
- borders and border styles;
- barcode width and height;
- padding and quiet zones;
- X-dimension and bar height;
- caption position and alignment;
- human-readable text;
- font family, size, and style;
- image rotation;
- units such as pixels, millimeters, points, and inches;
- image resolution and layout behavior.
Related documentation:
Directory:
generation/size/
Example class:
CustomizeBarcodeSize
Demonstrates how to control:
- barcode image width and height;
- X-dimension;
- bar height;
- auto-size modes;
- aspect ratio;
- padding and quiet zones;
- resolution-dependent dimensions.
Related documentation:
Directory:
generation/unit/
Example class:
UnitClassExample
Demonstrates the Unit API and conversion between supported measurement units.
These examples are useful when barcode dimensions must be defined in physical
units rather than only in pixels.
Related documentation:
Directory:
generation/xdimension/
Example class:
XDimensionExamples
Demonstrates how X-dimension affects:
- module and bar width;
- final image size;
- barcode readability;
- output at different resolutions;
- conversion between pixel and physical dimensions.
Related documentation:
Directory:
generation/checksum/
Example classes include:
EnforcedChecksumExamplesOptionalChecksumExamplesSetBarcodeChecksum
These examples demonstrate the difference between symbologies with:
- mandatory checksums that are always generated;
- optional checksums that can be enabled or disabled;
- reader-side checksum validation;
- normalized or expanded decoded text;
- checksum-aware regression tests.
The examples cover common 1D symbologies such as Code 39, Code 93, Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, and other formats with symbology-specific checksum rules.
Related documentation:
Directory:
generation/save_options/
Example classes include:
SaveGeneratedBarcodesSaveGeneratedImageExample
These examples demonstrate how to:
- save generated barcodes to files;
- save images to output streams;
- select an output image format;
- obtain a generated
BufferedImage; - use generated barcode images in memory-based workflows.
Related documentation:
Directory:
generation/print_options/
Example classes include:
PrintBarcodesPrintOptionsExample
These examples demonstrate barcode printing workflows, including:
- rendering a barcode for printing;
- working with printer graphics;
- controlling placement and dimensions;
- preparing barcode images for printed documents and labels.
Related documentation:
Directory:
src/test/java/com/aspose/barcode/guide/recognition/
These examples demonstrate how to read barcodes, restrict recognition to selected symbologies, work with image regions and input sources, inspect recognition metadata, and tune recognition quality and performance.
Main documentation section:
Directory:
recognition/choose_symbology/
Example class:
ChooseRecognitionSymbology
Demonstrates how to:
- recognize a specific barcode type;
- provide several expected
DecodeTypevalues; - use all supported types when the symbology is unknown;
- reduce unnecessary recognition work by selecting expected types.
Related documentation:
Directory:
recognition/input_sources/
Example class:
InputSourcesExamples
Demonstrates how to read barcodes from:
- image file paths;
- input streams;
- byte arrays;
BufferedImageobjects;- application-managed image sources.
Related documentation:
Directory:
recognition/barcode_properties/
Example classes include:
AnglesExampleConfigureSymbologyTypeExampleCoordinatesExampleReadingCodeTextExampleReadingCodeTextRawExampleReadingMetadataExampleResultValidationExample
These examples demonstrate how to retrieve and validate:
- recognized codetext;
- raw codetext bytes;
- barcode type;
- confidence and reading quality;
- barcode angle;
- bounding rectangle;
- quadrangle coordinates;
- extended recognition parameters;
- result validity and consistency.
Related documentation:
Directory:
recognition/roi/
Example class:
RegionOfInterestExamples
Demonstrates how to:
- restrict recognition to a selected rectangle;
- scan several regions independently;
- improve performance when the barcode location is known;
- avoid unrelated objects in complex images.
Related documentation:
Directory:
recognition/quality_settings/
Example class:
QualitySettingsExample
Demonstrates how recognition quality presets and individual settings affect barcode reading.
Use these examples when balancing:
- recognition speed;
- support for damaged or low-quality images;
- small barcode modules;
- image complexity;
- expected barcode quality.
Related documentation:
Directory:
recognition/performance/
Example classes include:
DeconvolutionModeExampleHighPerformanceModeExampleMinimalXDimensionExampleMultithreadReadingExampleQualityModeExampleReadingColorInvertedExampleReadingDamagedBarcodeExampleReadingLowResolutionBarcodeExampleRecognitionPresets
These examples demonstrate how to:
- select recognition presets;
- optimize for speed or quality;
- process several images in parallel;
- recognize low-resolution barcodes;
- recognize damaged or blurred symbols;
- handle inverted barcode colors;
- configure minimal X-dimension;
- use deconvolution-related recognition settings.
Related documentation:
Directory:
recognition/special_parameters/
Example classes include:
AllowIncorrectBarcodesExampleAustralianPostParametersExampleChecksumValidationExampleDetectEncodingExampleStripFNCExample
These examples demonstrate specialized reader behavior, including:
- reading barcodes that do not fully satisfy a symbology specification;
- checksum validation modes;
- automatic text encoding detection;
- handling FNC characters;
- Australian Post decoding parameters.
Related documentation:
Directory:
src/test/java/com/aspose/barcode/guide/complex/
Complex barcodes contain structured business data defined by payment, healthcare, postal, shipping, or identification standards. These examples demonstrate the full workflow:
- populate a typed complex codetext model;
- generate its carrier barcode;
- recognize the carrier symbology;
- decode the recognized text into a typed object;
- validate individual business fields.
Main documentation section:
Directory:
complex/introduction/
Explains the difference between:
- regular barcode generation with
BarcodeGenerator; - structured barcode generation with
ComplexBarcodeGenerator; - raw recognized text;
- typed decoding through
ComplexCodetextReader.
Related documentation:
Directory:
complex/generate/
Demonstrates how to:
- create typed business data;
- generate the standardized payload;
- configure carrier appearance;
- save complex barcodes to files or streams;
- verify generated output.
Related documentation:
Directory:
complex/read/
Demonstrates the two-stage recognition workflow:
- recognize the physical carrier barcode;
- pass recognized codetext to the matching complex decoder.
The examples also show how to handle unsupported data and null decoder results.
Related documentation:
Directory:
complex/supported_types/
The examples are grouped by standard.
| Directory | Structured data demonstrated | Related documentation |
|---|---|---|
swiss_qr/ |
Swiss QR payment data, creditor and debtor addresses, references, and messages | Swiss QR Barcodes |
hibc/ |
HIBC LIC product data and HIBC PAS healthcare records | HIBC Barcodes |
royal_mail_mailmark/ |
Royal Mail Mailmark 1D and Mailmark 2D postal data | Royal Mail Mailmark Barcodes |
maxicode/ |
Structured MaxiCode mode 2 and mode 3 data | MaxiCode Barcodes |
usa_driver_id/ |
AAMVA USA Driver ID data stored in PDF417 | USA Driver ID Barcodes |
The parent documentation page is available here:
Directory:
complex/examples/
Provides complete end-to-end tests that combine:
- business-object creation;
- image generation;
- carrier recognition;
- structured decoding;
- field-by-field validation;
- processing of several complex barcode types.
Related documentation:
Directory:
complex/troubleshooting/
Demonstrates how to distinguish between:
- image-recognition failures;
- carrier-type mismatches;
- structured-decoding failures;
- missing required fields;
- standard-specific range validation errors.
Related documentation:
Directory:
src/test/java/com/aspose/barcode/guide/common/
The classes in this directory support the examples and are not part of the public Aspose.BarCode API.
Provides shared operations such as:
- creating and checking output paths;
- validating generated files;
- recognizing generated images;
- comparing expected barcode type and text;
- matching exact text or an expected prefix;
- applying image transformations;
- generating degraded images for recognition tests;
- printing recognition diagnostics.
Describe the expected recognition result and define how decoded text is compared, for example by exact equality or prefix matching.
Provides reusable image-loading behavior for tests that process input images in different forms.
Applies an Aspose.BarCode license when one is available.
A license is optional for running the examples. Without a license, the library works in evaluation mode and evaluation limitations may apply.
Before running the examples, install or provide:
- JDK 17 or later;
- Git;
- internet access for the first dependency resolution;
- an optional Aspose.BarCode license.
Check the active Java version:
java -versionCheck the compiler version:
javac -versionBoth commands should report Java 17 or later.
This repository is configured with Gradle and includes the Gradle wrapper.
Run all tests:
./gradlew clean testRun all tests:
gradlew.bat clean testLinux and macOS:
./gradlew test --tests "com.aspose.barcode.guide.quickstart.QuickGenerationExamples"Windows:
gradlew.bat test --tests "com.aspose.barcode.guide.quickstart.QuickGenerationExamples"./gradlew test --tests "fully.qualified.ClassName.methodName"Replace the package, class, and method names with the example you want to run.
This repository does not include a Maven
pom.xml. The documented build commands therefore use the Gradle wrapper.
To use IntelliJ IDEA, Eclipse, or another Java IDE:
- clone the repository;
- open or import it as a Gradle project;
- select JDK 17 or later as the project SDK;
- allow Gradle to resolve dependencies;
- run the required TestNG class or method.
The examples are tests, so the IDE must use TestNG when launching them.
The examples use the following directory for input resources and generated output:
src/test/resources/
Files are organized by topic so that the output of each example can be inspected after the test completes.
Many generation tests follow this validation pattern:
- generate a barcode image;
- verify that the file exists and is not empty;
- read the generated image with
BarCodeReader; - compare the recognized type and codetext with the expected result.
This makes the examples useful both as documentation and as executable regression tests.
When adding or modifying examples, follow these conventions:
- keep one primary concept per test;
- use clear class-level and method-level Javadoc;
- use deterministic file names and dimensions;
- store test data under
src/test/resources; - verify generated output through recognition where practical;
- validate structured fields for complex barcode examples;
- keep package names lowercase;
- use
ExampleAssistandLicenseAssistwhere appropriate; - do not treat helper methods from
commonas public Aspose.BarCode API.
Confirm that Gradle is using JDK 17 or later:
./gradlew --versionThe JVM shown in the output must be Java 17 or later.
Check internet access, proxy configuration, and access to the configured Maven repositories. Then retry:
./gradlew --refresh-dependencies testUse the fully qualified TestNG class name:
./gradlew test --tests "com.aspose.barcode.guide.generation.xdimension.XDimensionExamples"Check the package declaration in the source file if the filter still does not match.
Check:
- selected
DecodeType; - X-dimension;
- bar height;
- image resolution;
- quiet zones and padding;
- foreground/background contrast;
- checksum settings;
- recognition quality settings.
Use the diagnostics in ExampleAssist and the related recognition examples when
investigating the result.
Configure the license through LicenseAssist.setupLicense() using the license
location expected by your local environment. Do not commit private license files
to the repository.
When contributing a new example:
- place it in the package that matches the related documentation topic;
- create a separate TestNG class when the topic is independent;
- add detailed Javadoc explaining what the class and every test method demonstrate;
- use fixed and reproducible test data;
- verify generated output when possible;
- add or update the corresponding documentation link in this README;
- avoid committing private license files or environment-specific paths.
- Aspose.BarCode for Java documentation
- Getting Started
- Developer Guide
- API Reference
- Product Page
- Download Aspose.BarCode for Java
- Free Support Forum
This repository contains example code and tests that use Aspose.BarCode for Java. Review the Aspose licensing terms before using the library in production.
Happy barcoding!