Barcodes in JasperReports

Three options exist, and the choice is mostly about maintenance and about what the symbol must contain.

Whatever is chosen, the library licences are permissive for this use: JasperReports 7 is distributed under the LGPL, Barcode4J and ZXing under the Apache License 2.0. This is unlike iText, which is AGPL or commercial, so a report that only needs a barcode has no licensing reason to move to another library.

The Barcode4J component is a separate artifact from the engine and is not pulled in by jasperreports. Add it next to the PDF exporter, the fonts and the expression compiler used by the other pages of this section. ZXing is declared explicitly, even for the component, for a reason explained below.

What the dependency tree showed in the run: jasperreports-barcode4j 7.0.8 brings net.sf.barcode4j:barcode4j 2.1 and declares com.google.zxing:core 3.4.0 as a compile dependency. With ZXing 3.5.4 declared in the project, Maven’s nearest-wins rule resolved core to 3.5.4, and the QR code of the component rendered and decoded with it. Declaring the version that the application wants, rather than relying on the transitive one, also keeps the component and the custom ZXing code of the later sections on the same encoder. javase is only needed by the image-expression alternative, for MatrixToImageWriter.

The Maven coordinates and versions are documented on Maven Central. The rest of the project, including the Spring Boot setup, is in Getting Started with Spring Boot.

In JasperReports 6 a barcode was a namespaced element in the jr component namespace, inside a componentElement, and the template was validated against a schema. Version 7 replaced the XML binding with Jackson, and the template has no namespace any more. A component is an element with kind="component", a position and a size, and it has one child, component, whose kind attribute names the component. For Barcode4J the names have the form barcode4j: followed by the symbology, and the value to encode is given by a codeExpression child. A v6 template that contains barcodes cannot be loaded by 7.0.8 and has to be converted with Jaspersoft Studio 7, which is finding O15 of the section’s list of outdated points. A quick way to confirm that a component kind is known is to misspell it: the engine reports the known type ids, which in the run were barcode4j:Codabar, barcode4j:Code128, barcode4j:Code39, barcode4j:DataMatrix, barcode4j:EAN128, barcode4j:EAN13, barcode4j:EAN8, barcode4j:Interleaved2Of5, barcode4j:PDF417, barcode4j:POSTNET, barcode4j:QRCode, barcode4j:RoyalMailCustomer, barcode4j:UPCA, barcode4j:UPCE and barcode4j:USPSIntelligentMail.

The following template is the shelf-label report of the Bookshelf store. Each label has the title of the book, a Code 128 with the internal SKU, an EAN-13 with the ISBN and a QR code that opens the product page. The ISBNs and SKUs are invented sample values, and shop.example.com is a reserved example domain.

The template is compiled, filled and exported like any other. The record below is the data row, with the getters that the bean data source reads. The class is a plain, runnable main method.

In the run, the PDF had one page, and a ZXing scan of the rendered page found the two Code 128 symbols with the two SKUs, the two EAN-13 symbols with the two ISBNs and the two QR codes with the two URLs. The pieces that the page relies on are documented in the Barcode4J sample and the engine’s generic compile and export calls in JasperReports Architecture & Lifecycle.

The component classes of 7.0.8 define the attributes below. All the component kinds share the codeExpression child and the evaluation attributes of every component (evaluationTime, and evaluationGroup when the time is Group), which matter when the code depends on a variable such as a report total that is only known at the end of the report. All linear and 2D kinds except the QR code also share the Barcode4J attributes orientation (up, left, down, right), moduleWidth, textPosition (none, bottom, top), quietZone, verticalQuietZone and a patternExpression child, which formats the human-readable text.

The table is read from the compiled classes of the 7.0.8 artifact, so attribute names are the ones that Jackson binds in a v7 template. Values such as the checksumMode strings (auto, check, add, ignore) are those of Barcode4J. The JasperReports engine’s own documentation of the components is the Barcode4J sample page, and the upstream project describes every symbology in the Barcode4J documentation and on its SourceForge project page. The QR code has been rendered with ZXing since JasperReports 6.0.2, before which the component had no QR code.

A second run exercised the other kinds in one template, one element per symbol, with the attributes in the table where relevant. The Code 128, Code 39, EAN-8 and UPC-A symbols decoded with the expected values. The Data Matrix, PDF417, POSTNET and USPS Intelligent Mail symbols rendered and were checked by eye on the page image, but were not scanned, so nothing here claims they are readable. The POSTNET and USPS symbols are US postal formats. The USPS Intelligent Mail symbol expects a 20, 25, 29 or 31 digit string, and the engine accepted a 31 digit sample value.

A barcode that is wrong is worse than no barcode, so the behaviour on bad input is worth knowing. In the run:

The checksumMode attribute decides what happens with the check digit for the symbologies that have one. With auto the encoder uses the default of the symbology, with check it verifies a supplied digit and with add it computes one.

A barcode component is drawn by Barcode4J at a size that comes from the symbol and from moduleWidth, then placed in the element rectangle. The element’s width and height therefore do not stretch the bars. This is the main source of surprises, so the points below are the result of rendering the same Code 128 in elements of different sizes:

The overall rule for a band is to size the symbol first, using moduleWidth and the number of characters, then set the element rectangle to that size plus the quiet zone, and finally make the band high enough for the element. For a fixed grid of labels, such as sheets of stickers, a detail band of fixed height, as described in JRXML Report Design, is simpler than a stretching band.

Barcode4J does not draw into the PDF directly. An image producer turns the symbol into an image, and the default is the SVG producer. The effect on a PDF is visible: in the run, the PDF of the label report had no image XObject on the page, so the bars are vector paths, sharp at any zoom, and the file is small. The raster producer is selected by a property, which can be set globally in jasperreports.properties, per report as a property element, or on a single element:

With the value image the same template produced one raster image per symbol: three images of between 96 and 327 pixels in width and 167 in height for three Code 128 elements, at the default resolution. The resolution is set by net.sf.jasperreports.components.barcode4j.image.resolution (300 by default), and the properties ...image.gray and ...image.antiAlias (both true by default) control the colour model and the smoothing. Anti-aliasing a bar code is harmful for a scanner, because the edge of a bar becomes grey. Prefer the default SVG producer for PDF output, and use the raster producer only for an exporter that cannot draw vectors. The QR code has its own producer property, net.sf.jasperreports.components.barcode4j.qrcode.producer.{alias}, and the character set of its payload is net.sf.jasperreports.components.qrcode.character.encoding, whose default in 7.0.8 is UTF-8. All of them are listed in the configuration reference.

The jasperreports-barbecue artifact wraps Barbecue 1.5-beta1, a project that has been abandoned upstream. Its coordinates are net.sf.jasperreports:jasperreports-barbecue with the same version as the engine, and it works in 7.0.8, but with a different, older template structure. In v7 JRXML its kind has no symbology suffix: the symbology is the type attribute.

With jasperreports-barbecue on the classpath the template compiled and filled, the PDF had a vector Code 128 and ZXing decoded it. The attribute names come from the component class, which also has checksumRequired, rotation and an applicationIdentifierExpression for GS1-128. Two other variants, barbecue:Code128 and barbecue:barbecue, were refused with the unresolved type id error shown above. The component’s types are those of the Barbecue library (Code 128 A, B and C, Code 39, Codabar, EAN-13, UPC-A, 2 of 7 and others), and it has no QR code, no Data Matrix and no PDF417. Because the upstream project is not maintained, the page recommends it only for a template that already uses it. The upstream projects are on SourceForge, and the engine’s Barbecue sample shows the component.

The image element prints what its expression returns, and the expression may return a java.awt.Image, a path or URL string, an input stream, or a net.sf.jasperreports.renderers.Renderable. A static helper that draws a QR code with ZXing 3.5.4 is therefore enough, and the template stays free of any component. This is the pattern for the QR code of an invoice, where the payload is built in Java, and also for the formats the Barcode4J component lacks, such as the Aztec code, which ZXing writes as well.

The class is made visible to the expressions with an import element, whose content is the class name in v7 JRXML (an import element with a value attribute, the form of the v6 import declaration, is not read: the compiler reported Syntax error on token "import" and the template did not compile). The image element declares the expression class so that the compiler knows the type:

Three details matter. The size in pixels is the resolution of the bitmap, not the printed size: 400 pixels in an 80 point frame is a bit more than 360 dpi, which is plenty. scaleImage="FillFrame" stretches the bitmap to the frame, and since the matrix was generated square and without margin, a square frame keeps the modules square. And the expression runs once per row, in the fill, so a heavy encoder should not be used for thousands of rows without a cache.

In the run, the PDF page contained one 400 by 400 raster image per row, the exporter embedded the bitmap as it was, and the QR codes decoded with the SKU URLs. Drawn at a larger size the edges of such a bitmap blur in a viewer. The next section avoids it.

A Renderable is the engine’s abstraction of something that can be drawn into an image slot, and the Graphics2DRenderable interface is the form that draws into a Java2D Graphics2D at the rectangle that the layout gives it. The PDF exporter draws such a renderable as vector graphics. A renderer that draws every dark module of a QR code as a rectangle gives a QR code that is sharp at any zoom and costs no bitmap. ZXing’s Encoder is used directly to get the module matrix without the quiet zone.

The base class of the renderer is AbstractRenderToImageAwareRenderer in 7.0.8. A source that names AbstractRenderToImageAwareRenderable is from a version before 7 and does not compile. The template places the renderer with an expression of the class net.sf.jasperreports.renderers.Renderable:

A first version of the renderer filled one rectangle per module, one fill call each. The page rendered, and it looked right, but ZXing could not decode the QR code, because the anti-aliased edges of adjacent rectangles left hairline seams between modules at 300 dpi. Collecting all the modules into one Path2D and filling it once, as in the listing, made the symbol decode. This is worth remembering for any renderer that draws a symbol from many shapes: draw the dark area as one path. With that change, the PDF page of the run contained no image XObject for the renderer, only the bitmap of the previous element, and the QR code decoded with the SKU URL.

The matrix returned by Encoder has no quiet zone, so the element must be surrounded by white space, at least four modules wide, as the QR standard requires. The listing is the minimal version. To add a logo, reduce the symbol with level H, draw the logo in the centre area and verify with a scanner that the result still decodes. The background, a custom foreground colour or rounded modules are all one-line changes in render, but contrast between modules and background is what a scanner needs, so a dark module colour on a light background is the safe choice. The API of the interface is in the JasperReports API documentation, and the ZXing library on the ZXing GitHub project with the API documentation.

The component and the image expression solve the drawing. What goes into the symbol is a separate decision.

A report that has a URL in the symbol often also prints it as text, for people who cannot scan it. A textField with hyperlinkType="Reference" also makes the printed text a clickable link in the PDF, as described in Hyperlinks, Bookmarks & Report Books.

In the Spring Boot service of the scenario, the template is compiled once at start-up or at build time, as in Spring Boot Integration, and filled per request. Three consequences for barcodes follow.

When the labels are only a part of a larger document, the PDF produced can be post-processed. A filled form or a signature is added after the export, as in Signing with iText. For a signed document, the symbol is part of the content that is signed, so it must be drawn before the signature, never after.

Older books and tutorials on JasperReports describe barcodes in ways that no longer apply to 7.0.8.

The Code 128, Code 39, EAN-8, EAN-13, UPC-A and QR symbols, the Barbecue Code 128 and both ZXing alternatives were scanned back from the rendered PDF. The Data Matrix, PDF417, POSTNET and USPS Intelligent Mail symbols were rendered and inspected visually only. The scan was done on the PDF rendered at 300 dpi on a screen, which says nothing about a thermal printer, a laser printer, a label’s material or a particular scanner. Verify each symbology in the real printing chain before a label design is approved. The product of this page is a template that is correct, not a guarantee that a given symbol is readable in a warehouse.