Barcode-Lib4J requires Java 11+
Package de.vwsoft.barcodelib4j.twod

Java Class «TwoDCode»

java.lang.Object
de.vwsoft.barcodelib4j.twod.TwoDCode
All Implemented Interfaces:
Cloneable
public class TwoDCode extends Object implements Cloneable
Main class of the package for creating and configuring 2D codes.

Usage:

  1. Providing common settings such as code type (QR Code, DataMatrix, ...), the content, character set and quiet zone.
  2. Providing type-specific settings for the 2D code type you want to create.
  3. Check compatibility between the content and selected charset using canEncode().
  4. Call buildSymbol() to generate the drawable code symbol.
Example: 
     // Step 1: Common settings
     TwoDCode tdc = new TwoDCode(TwoDType.QRCODE);
     tdc.setContent("Hello World!");
     tdc.setCharset(null); // null = ISO 8859-1, includes no ECI
     tdc.setQuietZone(TwoDType.QRCODE.getDefaultQuietZone());

     // Step 2: Type-specific settings
     tdc.setQRCodeVersion(QRCodeVersion.AUTO);
     tdc.setQRCodeErrCorr(QRCodeErrorCorrection.M);

     // Step 3 and 4: Generate drawable symbol
     TwoDSymbol symbol = null;
     if (tdc.canEncode()) {
       try {
         symbol = tdc.buildSymbol();
       } catch (Exception ex) {
         // Handle the Exception
       }
     }

  • Constructor Details

  • Method Details

    • setType

      public void setType(TwoDType codeType)
      Sets the type of the 2D code.
      Parameters:
      codeType - the type of the 2D code to set
      Throws:
      NullPointerException - if the provided code type is null

    • setContent

      public void setContent(String content)
      Sets the content to be encoded in the 2D code.

      GS1 DataMatrix and GS1 QR Code: It is recommended to validate the content using the GS1Validator class before setting. Please refer to the class documentation for the expected input format requirements. Example: 

          import de.vwsoft.barcodelib4j.oned.BarcodeException;
    import de.vwsoft.barcodelib4j.oned.GS1Validator;

    GS1Validator validator = null;
    try {
      validator = new GS1Validator(gs1Data, fnc1Char);
    } catch (BarcodeException ex) {
      // Validation failed
    }

    if (validator != null)
      twoDCode.setContent(validator.getContent());
      Parameters:
      content - the content to be encoded
      Throws:
      NullPointerException - if the provided content is null
      IllegalArgumentException - if the provided content is empty

    • setCharset

      public void setCharset(Charset charset)
      Specifies the character set used to encode the content in the 2D code.

      If set to null (default), no character set information (ECI) is built into the code, and the ISO 8859-1 character set is used. This is the default character set for all supported 2D types unless another character set is explicitly specified.

      DataMatrix: The current implementation allows the use of character sets other than ISO 8859-1 only when its size is set to AUTO.

      GS1 DataMatrix and GS1 QR Code: Specifying a character set is unnecessary since GS1 data consists only of ASCII characters, which are fully compatible with ISO 8859-1.

      Parameters:
      charset - the character set to be used for encoding the content, or null to indicate the default ISO 8859-1 charset with no ECI

    • setQuietZone

      public void setQuietZone(int sizeInModules)
      Sets the size of the quiet zone for the 2D code.

      For an explanation of what quiet zones are and the default quiet zone sizes for each 2D code type, see TwoDType.getDefaultQuietZone().

      Parameters:
      sizeInModules - the size of the quiet zone in modules
      Throws:
      IllegalArgumentException - if the specified size is negative

    • setQRCodeVersion

      public void setQRCodeVersion(QRCodeVersion version)
      Sets the version of the QR Code.

      The version determines the size and data capacity of the QR Code. Valid versions range from 1 (21x21 modules) to 40 (177x177 modules). Use QRCodeVersion.AUTO to automatically select the smallest version capable of encoding the content.

      Parameters:
      version - the version of the QR Code or QRCodeVersion.AUTO
      Throws:
      NullPointerException - if the specified version is null

    • setQRCodeErrCorr

      public void setQRCodeErrCorr(QRCodeErrorCorrection errorCorrectionLevel)
      Sets the error correction level for QR Code.

      The error correction level specifies the amount of redundant data added to the symbol to enable error recovery. QR Codes support four levels of error correction: L (Low - ~7%), M (Medium - ~15%), Q (Quartile - ~25%), and H (High - ~30%). The higher the error correction level, the more redundancy is added, resulting in a higher resistance to errors, but also in a larger symbol size.

      Parameters:
      errorCorrectionLevel - the error correction level to set for QR Code
      Throws:
      NullPointerException - if the specified error correction level is null

    • setDataMatrixSize

      public void setDataMatrixSize(DataMatrixSize size)
      Sets the size of the DataMatrix symbol.

      The size determines the data capacity of the DataMatrix symbol. Valid sizes range from 10x10 modules to 144x144 modules. The 30 available sizes include 24 square and 6 rectangular variants. Use DataMatrixSize.AUTO to automatically select the smallest size capable of encoding the content.

      Parameters:
      size - the size of the DataMatrix symbol or DataMatrixSize.AUTO
      Throws:
      NullPointerException - if the specified size is null

    • setDataMatrixShape

      public void setDataMatrixShape(DataMatrixShape shape)
      Sets the shape of the DataMatrix symbol.

      Valid values are:

      Note: This setting is ignored when a fixed size (not AUTO) is specified via setDataMatrixSize, as the size already determines whether the symbol is square or rectangular.

      Parameters:
      shape - the shape of the DataMatrix symbol
      Throws:
      NullPointerException - if the provided shape is null

    • setPDF417Size

      public void setPDF417Size(PDF417Size size)
      Sets the size of the PDF417 symbol.

      The PDF417 symbol size is specified in terms of the number of columns and rows. The number of columns can range from 1 to 30, and the number of rows can range from 3 to 90. If the columns or rows value is set to 0, the respective value is automatically selected based on the content to be encoded.

      Parameters:
      size - the size of the PDF417 symbol
      Throws:
      NullPointerException - if the provided size is null

    • setPDF417ErrCorr

      public void setPDF417ErrCorr(PDF417ErrorCorrection errorCorrectionLevel)
      Sets the error correction level for PDF417.

      The parameter specifies the amount of redundant data added to the symbol to enable error recovery. The higher the error correction level, the more redundancy is added, resulting in a higher resistance to errors, but also in a larger symbol size. PDF417 supports error correction levels from 0 to 8.

      Parameters:
      errorCorrectionLevel - the error correction level to set for PDF417
      Throws:
      NullPointerException - if the specified error correction level is null

    • setAztecSize

      public void setAztecSize(AztecSize size)
      Sets the size of the Aztec code symbol.

      Aztec symbols come in two types that differ in their internal structure. Compact symbols (1 to 4 layers, 15x15 to 27x27 modules) have a smaller bullseye finder pattern and less error correction overhead, making them efficient for small data amounts. Normal symbols (1 to 32 layers, 19x19 to 151x151 modules) have a larger bullseye finder pattern and more robust error correction, providing better readability and greater data capacity. Use AztecSize.AUTO to automatically select the smallest size capable of encoding the content, preferring compact sizes when possible.

      Parameters:
      size - the size of the Aztec symbol or AztecSize.AUTO
      Throws:
      NullPointerException - if the specified size is null

    • setAztecErrCorr

      public void setAztecErrCorr(int errorCorrectionLevel)
      Sets the error correction level for Aztec, specified in percent.

      The error correction level determines the amount of redundancy data added to the symbol for error detection and correction. Aztec symbols support error correction levels ranging from 5% to 95%. Higher error correction levels add more redundancy data, increasing the symbol's ability to withstand errors but also increasing its size.

      Parameters:
      errorCorrectionLevel - the error correction level for Aztec, specified in percent
      Throws:
      IllegalArgumentException - if the specified error correction level is outside the valid range

    • canEncode

      public boolean canEncode()
      Checks if the specified charset can encode the given content.

      If no character set is specified (null), ISO 8859-1 is checked as this is the default charset used by all supported 2D code implementations.

      For several reasons, it is recommended to call this method before building the 2D code symbol using the buildSymbol() method:

      • Some 2D code implementations (QR Code, Aztec) will generate the symbol even if the content cannot be encoded correctly with the specified charset, resulting in a 2D code that no longer contains the original information.
      • In contrast, other implementations (DataMatrix, PDF417) will properly throw an exception if the content cannot be encoded. Such exceptions can be avoided by having this method perform the check in advance.
      Returns:
      true if the specified charset can encode the content, false otherwise

    • buildSymbol

      public TwoDSymbol buildSymbol() throws Exception
      Generates a drawable 2D symbol based on the provided properties.

      Any exceptions thrown by this method are forwarded exceptions caused by the internal call to ZXing's Writer#encode(). Since this method is implemented differently in the ZXing classes depending on the code type, it can throw different exceptions, even though only WriterException is declared by the Writer#encode() methods. Therefore, all exceptions are forwarded as a generalized java.lang.Exception.

      For example, the DataMatrixWriter and the PDF417Writer may throw different exceptions, even for the same reason, such as when non-encodable characters are detected in the content. While the first Writer throws the declared WriterException, the second may throw an IllegalArgumentException.

      The Writer implementations of the other two code types (QR Code and Aztec) do not throw an exception at all when encountering non-encodable characters, but instead encode the content with a loss of information due to incorrect character encoding. This underlines the importance of checking this first by calling canEncode().

      Returns:
      a TwoDSymbol object representing the generated 2D symbol
      Throws:
      Exception - if an error occurs during the symbol generation process

    • getType

      public TwoDType getType()
      Returns the type of the 2D code.
      Returns:
      the type of the 2D code

    • getContent

      public String getContent()
      Returns the content encoded in the 2D code.
      Returns:
      the content encoded in the 2D code

    • getCharset

      public Charset getCharset()
      Returns the character set used for encoding the content.
      Returns:
      the character set used for encoding the content

    • getQuietZone

      public int getQuietZone()
      Returns the size of the quiet zone around the 2D code.
      Returns:
      the size of the quiet zone around the 2D code

    • getQRCodeVersion

      public QRCodeVersion getQRCodeVersion()
      Returns the version of the QR Code.
      Returns:
      the version of the QR Code

    • getQRCodeErrCorr

      public QRCodeErrorCorrection getQRCodeErrCorr()
      Returns the error correction level of the QR Code.
      Returns:
      the error correction level of the QR Code

    • getDataMatrixSize

      public DataMatrixSize getDataMatrixSize()
      Returns the size of the DataMatrix symbol.
      Returns:
      the size of the DataMatrix symbol

    • getDataMatrixShape

      public DataMatrixShape getDataMatrixShape()
      Returns the shape of the DataMatrix symbol.
      Returns:
      the shape of the DataMatrix symbol

    • getPDF417Size

      public PDF417Size getPDF417Size()
      Returns the size of the PDF417 symbol.
      Returns:
      the size of the PDF417 symbol

    • getPDF417ErrCorr

      public PDF417ErrorCorrection getPDF417ErrCorr()
      Returns the error correction level of the PDF417.
      Returns:
      the error correction level of the PDF417

    • getAztecSize

      public AztecSize getAztecSize()
      Returns the size of the Aztec symbol.
      Returns:
      the size of the Aztec symbol

    • getAztecErrCorr

      public int getAztecErrCorr()
      Returns the error correction level of the Aztec.
      Returns:
      the error correction level of the Aztec

    • clone

      public TwoDCode clone()
      Returns a copy of this object.

      The returned copy is independent of the original and can be modified without affecting it. All instance members are either primitive or immutable types, or will be automatically rebuilt when any of the instance's properties change. Thus, the copy can be handled as if it were a "deep copy".

      Overrides:
      clone in class Object
      Returns:
      a copy of this object