How to create, print QR Code in Eclipse BIRT reports?

This page provides a detaied technical reference for BIRT report developers who need to generate QR Code barcodes within Eclipse BIRT reports. QR Code is a matrix (two dimensional) barcode symbology created by Denso Wave in 1994. QR Codes are widely used in marketing, inventory tracking, payment systems, and document management due to their large data capacity, error correction, and fast readability.


The BarcodeLib BIRT QR Code Generator is an Eclipse BIRT Custom Extended Report Item built on the BarcodeLib Java Barcode Generator library. It enables you to generate high quality QR Code barcode images directly in BIRT reports without writing Java code. All QR Code properties are configured exclusively in the Report Item Property view of your Report Design file (.rptdesign). The plugin is distributed as a single JAR file, requires no registration key or activation code, and is easy to redistribute. It generates high quality QR Code images in GIF, PNG, or JPG format.

The BarcodeLib BIRT Barcode QR Code Generator is an Eclipse BIRT Custom Extended Report Item that allows you to easily generate and print high quality linear (1D) and two dimensional (2D) barcodes in your BIRT reports. The QR Code component specifically targets the QR Code symbology, which is valued for its ability to encode a wide variety of data types (numeric, alphanumeric, byte, and Kanji) and its configurable error correction.

Valid data scope for QR Code encoding:

• Numeric data : digits 0 - 9.
• Alphanumeric data : digits 0 - 9, uppercase letters A - Z, and nine special characters: space, $, %, *, +, -, ., /, :.
• Byte data : default character set is ISO/IEC 8859-1. This includes all ASCII values 0–255 and can be extended via ECI.
• Kanji characters : Japanese characters according to the JIS X 0208 standard.

Note:
The QR Code barcode is implemented as a custom report item that appears in the BIRT Palette after installation. You can drag and drop it onto your report layout, and then configure all barcode properties through the standard Property view. No additional Java coding or scripting is required for basic use cases.

Note about redistribution:
The plugin is distributed as a single JAR file. You can include this JAR in your BIRT report deployment package, and it works both in the BIRT Report Designer (for design time) and the BIRT Report Runtime (for headless report generation).

Here we will explain how to generate and print QR Code barcodes in a BIRT report.

• Create a new empty report in your BIRT report barcoding project
• Drag the barcode report item from the Palette
• Edit the barcode parameters
  
  Right click the barcode item you have added and select Properties from the context menu. This opens the General tab, where you will find all barcode properties.
  • For static text data, enclose the value in double quotation marks (e.g., "12345").
  • For data set expressions, do not use quotes; instead, enter an expression such as row["CUSTOMERNUMBER"].
• Change the barcode type to QR Code
  In the General tab, locate the Barcode Type property. Change it from the default (e.g., Code 128) to QR Code.
• Preview the report
  Click the Preview button (or View Report) on the toolbar. A QR Code barcode image should be printed on your BIRT report.
• Encode barcode data from a BIRT report data set (optional)
  
  If you want to generate barcodes dynamically from a data set, input an expression into the Data property. For example: row["CUSTOMERNUMBER"]. This will take the value of the CUSTOMERNUMBER column from the current row of the data set.

Note:
When using a data set expression like row["CUSTOMERNUMBER"], ensure that the column name exactly matches the data set alias. The expression should not be enclosed in quotation marks. Otherwise, it will be treated as a literal string.

Here we will learn about advanced QR Code data encoding settings available in the Report Item Property view, including data mode selection, character sets, and maximum data length.

QR Code supports the following data types in BIRT reports:

• Numeric data : digits 0 - 9.
• ASCII text : standard English letters, digits, and punctuation.
• Unicode multilingual text : characters from various writing systems (e.g., Arabic, Greek, Thai, Chinese) when encoded via Byte mode with UTF 8.
• Byte data : default character set is ISO/IEC 8859 1; can be extended via ECI.
• Kanji characters : Japanese characters according to JIS X 0208.

The Data Mode property controls how your data is encoded. Choosing the right mode makes QR Codes smaller and more scannable. The system can automatically optimize encoding efficiency based on input content when AUTO is selected. All Data Mode settings are configured in the Report Item Property panel.

• Auto Mode : The library automatically selects the optimal encoding mode (Numeric, Alphanumeric, Byte, or Kanji) based on the input data. This is recommended for most BIRT reports.
• Numeric Mode : For digit only data (0 - 9). This is the most compact encoding for numeric strings.
• AlphaNumeric Mode : For uppercase letters (A - Z), digits (0 - 9), and the nine special characters: space, $, %, *, +, -, ., /, :.
• Byte Mode : For binary data and extended character sets (including Unicode). Required when EncodeUnicodeText is used or when data contains non ASCII characters.
• Kanji Mode : For JIS X 0208 Kanji characters. This mode compacts each Kanji character into 13 bits.

Note

Setting Data Mode to a value incompatible with the actual data (e.g., using NUMERIC for text containing letters) will cause encoding errors or unreadable QR Codes. Always double check your data set field type before setting DataMode. When in doubt, use AUTO.

QR Codes have a maximum data capacity that depends on the encoding mode and the QR Code version. Version 40 with error correction level L (lowest) provides the largest capacity. These limits are critical for BIRT reports that need to encode large data, such as long product descriptions or multiple data points. The limits for Version 40-L are:

• Numeric data : 7,089 characters
• Alphanumeric data : 4,296 characters
• Byte data : 2,953 characters
• Kanji data : 1,817 characters

Note

In BIRT reports, you can add a filter or a validation rule to the data set to ensure that the column used for barcode data does not exceed the maximum length for the chosen mode and version. For example, you can use a BIRT expression like row["DATA_FIELD"].length() <= 4296 to conditionally display a warning or truncate the data.

Here we will learn how to encode special text formats (ASCII non printable characters, Unicode text, GS1 data, binary data, and Kanji text) in BIRT reports.

ASCII non printable characters (e.g., Carriage Return [CR], Tab, Line Feed [LF]) do not have visible label. However, you can encode them in BIRT QR Codes using the Process Tilde property.

1. In the Report Item Property view, set Process Tilde to true.
2. Set DataMode to BYTE
3. Represent each non printable character as a three digit ASCII value prefixed with ~. For example:
   • Carriage Return (CR, ASCII 13) > ~013
   • Line Feed (LF, ASCII 10) > ~010
   • Tab (ASCII 9) > ~009
4. Set the Data property to a string that includes these escape sequences. For example: "Line1~013~010Line2" encodes "Line1", then CR, then LF, then "Line2".

Note

Incorrect ASCII code formatting (e.g., using ~13 instead of ~013) will lead to an invalid QR Code image output in the BIRT report. Always use exactly three digits.

QR Codes do not natively support Unicode text (e.g., Thai, Arabic, Greek, Chinese) in the default encoding modes. However, BIRT allows you to work around this by using binary data encoding methods: converting text to UTF 8 byte arrays and then using the tilde escape sequences.

1. In the Report Item Property view, set Process Tilde to true.
2. Set Data Mode to BYTE.
3. Convert the Unicode text to a UTF 8 byte array. For each byte, format it as ~ddd (three digit decimal value). For example, the Unicode string "你好" might be represented as ~228~189~160~229~165~189 (depending on the UTF 8 encoding).
4. Set the Data property to the concatenated tilde escaped string.

GS1 QR Codes are used in supply chain and retail reports to encode standardized data such as product expiration dates, batch numbers, and Global Trade Item Numbers (GTIN).

1. In the Report Item Property view, set FNC1 Mode to ENABLE.
2. Set DataMode to AUTO.
3. Enter GS1 formatted data with Application Identifier (AI) codes enclosed in parentheses. Example: "(01)12345678901234(17)250101(10)ABC123".
4. The library automatically inserts the FNC1 character in the first position and removes the parentheses for encoding.

Note

GS1 data must follow strict formatting rules. AI codes must be enclosed in parentheses, and the data lengths must match the requirements for each AI (e.g., AI 17 for expiration date requires exactly 6 digits in YYMMDD format). Incorrect formatting will make the QR Code unreadable by GS1 barcode scanners.

Most 2D barcodes, including QR Codes, support binary data encoding. This is useful for BIRT reports that need to encode file contents, serialized objects, or other raw byte streams.

1. In the Report Item Property view, set DataMode to BYTE.
2. Convert the binary data to a byte array. For each byte, format it as ~ddd (three digit decimal value).
3. Set the Data property to the concatenated tilde escaped string.

Kanji characters (JIS X 0208) can be compacted into 13 bits, producing smaller QR Codes than Byte mode. The BarcodeLib library supports Kanji mode via the tilde escape sequence ~9ddddd.

1. In the Report Item Property view, set Process Tilde to true.
2. Set Data Mode to KANJI.
3. For each Kanji character, obtain its Shift JIS value (a two byte value in the ranges 0x8140 - 0x9FFC or 0xE040 - 0xEBBF). Convert that value to a decimal integer and format it as ~9ddddd (five digits, padding with leading zeros if necessary). Example: the Kanji character "点" might be represented as ~937727.
4. Set the Data property to the concatenated string of these escape sequences.

This section covers how to customize the physical size, quiet zones, colors, and image quality of QR Codes in BIRT reports using the Report Item Property view.

QR Codes are square, so setting the width automatically sets the height to the same value. This ensures a consistent module aspect ratio.

• In the Report Item Property view, set the BarcodeWidth property to the desired pixel size (e.g., 200).
• The height is automatically derived from the width, producing a square QR Code.

Note

Do not set the width to a value smaller than 100 pixels for typical QR Codes containing more than a few characters. Very small QR Codes may be unreadable by standard scanners, especially when printed.

Quiet zones are the empty spaces around the QR Code that scanners require to detect the symbol boundaries. The QR Code specification mandates a quiet zone of at least 4 modules (4x the module width) on all sides. You can set these margins in the Report Item Property panel using four properties:

• LeftMargin
• RightMargin
• TopMargin
• BottomMargin

Note

Set each margin to at least 4X, where X is the module width. For example, if X = 2 pixels, set margins to at least 8 pixels. Skipping quiet zones or setting them too small will make QR Codes unreadable. Also, ensure that quiet zones do not overlap with other report items (e.g., Label or Data items) in your layout.

BIRT allows you to customize QR Code colors (module color and background color) and image quality directly in the Report Item Property panel. This is useful for matching your report's branding or style.

• Fore Color : The color of the modules (the dark squares). Default is black. You can change it to any color, but ensure sufficient contrast with the background.
• Back Color : The background color of the QR Code image. Default is white. Supports standard colors and also transparent backgrounds.
• Transparent Back Color : Set this property to true to make the background transparent. This is useful if the BIRT report has a custom background color or image (added via the Master Page).
• Resolution : Set a higher resolution (e.g., 300 DPI) for printing purposes. The default is 72 DPI, which is suitable for screen display.

Note

For reliable scanning, use dark modules on a light background. Light modules on a dark background (inverted) may work with some scanners but are not recommended for general use.

For enterprise level BIRT reports, you may need advanced QR Code settings such as error correction level, version control, structured append, FNC1 for GS1, and ECI mode. All these options are configured in the Report Item Property panel.

QR Codes use Reed Solomon error correction to recover data if the barcode is damaged or partially obscured. There are four levels, each providing a different percentage of recoverable data. You can set the ECL property in the Report Item Property panel to one of the following values:

• L : 7% recovery (default). Suitable for clean environments and small barcodes.
• M : 15% recovery. Recommended for typical use.
• Q : 25% recovery. Suitable for environments where damage is possible.
• H : 30% recovery. Highest level, used for critical data or harsh environments.

Higher error correction levels increase the barcode size because more error correction codewords are added. For BIRT reports that will be printed on labels that may be scratched or smudged, consider using level Q or H.

QR Codes have 40 versions (Version 1 to Version 40). Higher versions produce larger symbols (more modules) and can store more data. You can set the Version property in the Report Item Property panel to a specific value between 1 and 40.

Note
Manually selecting a version that is too small for your data will cause an encoding error. If you have strict layout constraints (e.g., the QR Code must fit in a fixed size cell), you can pre calculate the maximum data capacity for each version and ensure your data does not exceed that limit.

For large data that exceeds the maximum QR Code capacity, use Structured Append mode to split the data across up to 16 QR Code symbols. The symbols can be scanned in sequence to reconstruct the original data. This is useful for BIRT reports that need to encode very long text, multiple data points, or large binary objects.

• Structured Append : Set to true to enable this mode.
• SymbolCount : The total number of symbols in the sequence (e.g., 3).
• SymbolIndex : The position of the current symbol in the sequence (starting from 0 for the first symbol).
• FileId : A unique integer identifier (same for all symbols in the sequence) to group them.

This mode identifies GS1 compliant barcode data. It is the same as the GS1 QR Code mode described in the above section. Set FNC1 Mode to ENABLE in the Report Item Property panel. This tells scanners that the QR Code contains GS1 formatted data, ensuring compatibility with supply chain systems.

Here we have provided a complete, step by step workflow for generating QR Code barcodes in BIRT reports for Eclipse Java projects. All QR Code properties are configured in the Report Item Property view of the barcode report item, ensuring consistency and ease of management across your BIRT reports.

Using the BarcodeLib QR Code BIRT Generator, you can customize QR Code encoding, size, error correction, and advanced features (Structured Append, FNC1, ECI) to meet your BIRT report's specific requirements, whether for marketing, inventory, payment systems, or enterprise document management. The plugin is mature, redistributable as a single JAR, and requires no registration key. By following the validation notes and best practices outlined in this guide, you can ensure accurate, scannable QR Codes in all your BIRT reports.