Package com.iizix.barcode

Class BarcodeBuilder

java.lang.Object
com.iizix.barcode.BarcodeBuilder
All Implemented Interfaces:
Serializable, Cloneable
public final class BarcodeBuilder extends Object implements Cloneable, Serializable
The barcode builder that is used to set parameters like:
  • validation: can be turned on or off to perform parameter validation,
  • text: required parameter that assign the text contents for the barcode,
  • size: the requested size of the barcode, if not specified, the smallest size is assumed,
  • errorCorrection: what degree of error correction to use depending on barcode,
  • charset: what character set or name to use where applicable,
  • shape: Specifies the matrix shape for Data Matrix,
  • margin: margin, in pixels, to use when generating the barcode, the meaning can vary by format,
  • compact: whether to use compact mode for PDF417 barcodes,
  • compaction: what compaction mode to use for PDF417 barcodes,
  • dimensions: minimum and maximum number of rows and columns for PDF417 barcodes,
  • layers: required number of layers for AZTEC barcodes,
  • version: exact version for encoded QR_CODE barcodes,

Only the text parameter is required, but the size parameter is recommended.

Once parameters are set, the builder can produce a BarcodeURN that can be used within IIZI in various places, create an SVG image String with or without XML header, a java.awt.BufferedImage, or write the barcode to a file or an output stream.

NOTE: This class is not thread safe by design in order to keep garbage collection as low as possible. If you need multiple thread access, make sure to synchronize on the BarcodeBuilder instance you use between the threads.

Author:
Christopher Mindus
See Also:

  • Method Details

    • validate

      public BarcodeBuilder validate(boolean isEnabled)
      Turns validation mode on or off.
      Parameters:
      isEnabled - Flag to enable validation.
      Returns:
      This instance in order to be able to concatenate methods for this builder.

    • text

      public BarcodeBuilder text(String text) throws BarcodeValidationException
      Assign the text contents for the barcode.

      The text contents is directly validated if validation is enabled, otherwise it will be validated when the builder performs some output operation such as creating the BarcodeURN or an image (SVG, BufferedImage or written to file or output stream).

      Parameters:
      text - The text contents.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      NullPointerException - If the text is null.
      BarcodeValidationException - If the text is not valid for the barcode type or format when validation mode is enabled.

    • size

      public BarcodeBuilder size(int size)
      Assigns the size for a as the width and height, typically used for a 2-dimensional barcode such as BarcodeType.AZTEC, BarcodeType.DATA_MATRIX and BarcodeType.QR_CODE.

      Note that the width and height values can be enlarged if the barcode bitmap does not fit inside the requested dimension.

      Parameters:
      size - The width and height to is set to this size.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      IllegalArgumentException - If the size is negative.

    • size

      public BarcodeBuilder size(int width, int height)
      Assigns the width and height for the barcode.

      Note that the values can be enlarged if the barcode bitmap does not fit inside the requested dimension.

      Parameters:
      width - The width.
      height - The height.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      IllegalArgumentException - If the size is negative.

    • errorCorrection

      public BarcodeBuilder errorCorrection(ErrorCorrectionLevel errorCorrectionLevel)
      Assigns the error correction for a QR code. If validation mode is not enabled and this barcode type or format is not BarcodeType.QR_CODE, then this method will do nothing.
      Parameters:
      errorCorrectionLevel - The error correction level, or null to reset to the default ErrorCorrectionLevel.L level used by default.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - If this barcode type or format is not a BarcodeType.QR_CODE and validation mode is enabled.

    • errorCorrection

      public BarcodeBuilder errorCorrection(int errorCorrectionLevel)
      Assigns the error correction for a AZTEC or PDF417 barcodes. If validation mode is not enabled and this barcode type or format is not BarcodeType.AZTEC or BarcodeType.PDF_417, then this method will do nothing.
      Parameters:
      errorCorrectionLevel - For Aztec the value represents the minimal percentage (0-100) of error correction words.
      For PDF417, valid values being 0 to 8.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      IllegalArgumentException - If the errorCorrectionLevel value is out of range for the barcode type or format.
      BarcodeValidationException - If this barcode type or format is not a BarcodeType.QR_CODE and validation mode is enabled.

    • charset

      public BarcodeBuilder charset(String charsetName)
      Specifies what character set to use for encoding valid for the barcode types or formats BarcodeType.AZTEC, BarcodeType.PDF_417 and BarcodeType.QR_CODE. If validation mode is enabled for these barcode type or format, a BarcodeValidationException is thrown, otherwise this method will do nothing.
      Parameters:
      charsetName - The character set name, or null reset to default value.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - If this barcode type or format is not a BarcodeType.AZTEC, BarcodeType.PDF_417 or BarcodeType.QR_CODE and validation mode is enabled, or if it is one of these barcode types or formats and the charsetName is illegal or unsupported in this Java VM.

    • charset

      public BarcodeBuilder charset(Charset charset)
      Specifies what character set to use for encoding valid for the barcode types or formats BarcodeType.AZTEC, BarcodeType.PDF_417 and BarcodeType.QR_CODE. If validation mode is enabled for these barcode type or format, a BarcodeValidationException is thrown, otherwise this method will do nothing.
      Parameters:
      charset - The character set, or null reset to default value.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - If this barcode type or format is not a BarcodeType.AZTEC, BarcodeType.PDF_417 or BarcodeType.QR_CODE and validation mode is enabled.

    • shape

      public BarcodeBuilder shape(SymbolShapeHint shape)
      Specifies the matrix shape for Data Matrix. It can be used to force square or rectangular symbols. Only the barcode type or format BarcodeType.DATA_MATRIX supports this method. If validation mode is enabled and the barcode is not DATA_MATRIX, a BarcodeValidationException is thrown, otherwise this method will do nothing.
      Parameters:
      shape - The shape, or null to reset to default {@link SymbolShapeHint#FORCE_NONE}. Valid values are otherwise {@link SymbolShapeHint.FORCE_NONE}, {@link SymbolShapeHint.FORCE_SQUARE} or {@link SymbolShapeHint.FORCE_RECTANGLE}.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - If this barcode type or format is not a BarcodeType.DATA_MATRIX and validation mode is enabled.

    • margin

      public BarcodeBuilder margin(int margin)
      Sets the margin in pixels to use when generating the barcode, the meaning can vary by format. Supported barcodes all one-dimensional barcode formats or types, BarcodeType.PDF_417 and BarcodeType.QR_CODE. For other formats, this method will do nothing unless validation mode is enabled in which case a BarcodeValidationException is thrown.

      All supported barcode formats or types:

      Unsupported barcode formats or types:

      Parameters:
      margin - The margin or a negative value (e.g. @code -1}) to reset to default value.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - If this barcode type or format is not supported and validation mode is enabled.

    • compact

      public BarcodeBuilder compact(boolean compact)
      Sets whether to use compact mode for BarcodeType.PDF_417 barcodes.

      This method will do nothing for other barcode formats or types if validation is not enabled, otherwise a BarcodeValidationException is thrown.

      Parameters:
      compact - Flag indicating compact PDF417 mode, default is false.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - If this barcode type or format is not BarcodeType.PDF_417 and validation mode is enabled.

    • compaction

      public BarcodeBuilder compaction(Compaction compaction)
      Sets whether to use compaction mode for BarcodeType.PDF_417 barcodes.

      This method will do nothing for other barcode formats or types if validation is not enabled, otherwise a BarcodeValidationException is thrown.

      Parameters:
      compaction - The PDF417 Compaction mode, or null to reset to default Compaction.AUTO Compaction mode. Valid values are: {@link Compaction#AUTO}, {@link Compaction#TEXT}, {@link Compaction#BYTE} or {@link Compaction#NUMERIC}.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - If this barcode type or format is not BarcodeType.PDF_417 and validation mode is enabled.

    • dimensions

      public BarcodeBuilder dimensions(int minCols, int maxCols, int minRows, int maxRows)
      Sets the dimensions for a PDF417 barcode, i.e. the minimum and maximum number of rows and columns.

      This method will do nothing for other barcode formats or types if validation is not enabled, otherwise a BarcodeValidationException is thrown.

      To reset the values to default, set all parameter values to zero.

      Parameters:
      minCols - Minimum allowed columns.
      maxCols - Maximum allowed columns.
      minRows - Minimum allowed rows.
      maxRows - Maximum allowed rows.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - If this barcode type or format is not BarcodeType.PDF_417 and validation mode is enabled, or if either value is zero or a minimum value equal or larger than its corresponding maximum value.

    • layers

      public BarcodeBuilder layers(int number)
      Specifies the required number of layers for an BarcodeType.AZTEC barcode.

      This method will do nothing for other barcode formats or types if validation is not enabled, otherwise a BarcodeValidationException is thrown.

      To reset the values to default, set the layerNumbers value to zero.

      Parameters:
      number - Required number of layers for AZTEC barcodes:
      • A negative number (-1, -2, -3, -4) specifies a compact Aztec code.
      • Zero indicates to use the minimum number of layers (the default).
      • A positive number (1, 2,... 32) specifies a normal (non-compact) Aztec code.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - If validation mode is enabled and this barcode type or format is not BarcodeType.AZTEC or number is less than -4 or larger than 32.

    • version

      public BarcodeBuilder version(int number)
      Specifies the exact version of QR code to be encoded.

      This method will do nothing for other barcode formats or types if validation is not enabled, otherwise a BarcodeValidationException is thrown.

      To reset the version to default recommended version depending of the error correction and the barcode text content, set the number value to zero.

      Parameters:
      number - Version number: zero for default, otherwise a value between 1 and 40.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - If validation mode is enabled and this barcode type or format is not BarcodeType.QR_CODE or version number is not in the range of 1 to 40.

    • checkParams

      public BarcodeBuilder checkParams() throws BarcodeValidationException
      Checks the basic parameters, regardless of if validation mode is enabled or not.
      Returns:
      This instance in order to be able to concatenate methods for this builder.
      Throws:
      BarcodeValidationException - For missing or invalid values.

    • asURNString

      public String asURNString() throws BarcodeException
      Gets the String to as a {@link BarcodeURN} for this barcode.
      Returns:
      The BarcodeURN String.
      Throws:
      BarcodeException - If there are missing or invalid parameters assigned in this builder encountered during barcode encoding.

    • asURN

      public BarcodeURN asURN() throws BarcodeException
      Gets the String to as a {@link BarcodeURN} for this barcode.
      Returns:
      The BarcodeURN String.
      Throws:
      BarcodeException - If there are missing or invalid parameters assigned in this builder encountered during barcode encoding.

    • asSVG

      public String asSVG() throws BarcodeException
      Creates an SVG image for the barcode.
      Returns:
      The SVG image string without XML header.
      Throws:
      BarcodeException - If there are missing or invalid parameters assigned in this builder encountered during barcode encoding.

    • asBufferedImage

      public BufferedImage asBufferedImage() throws BarcodeException
      Creates a BufferedImage of the barcode that can be used in java.awt transformations or other operations.
      Returns:
      The BufferedImage.
      Throws:
      BarcodeException - If there are missing or invalid parameters assigned in this builder encountered during barcode encoding.

    • toOutputStream

      public void toOutputStream(OutputStream pngOutputStream) throws BarcodeException, IOException
      Writes the barcode to an output stream in .PNG format.
      Parameters:
      pngOutputStream - The output stream that will receive the contents of the PNG file image data of the barcode.
      Throws:
      BarcodeException - If there are missing or invalid parameters assigned in this builder encountered during barcode encoding.
      IOException - For I/O errors writing the file.

    • toOutputStream

      public void toOutputStream(String formatName, OutputStream outputStream) throws BarcodeException, IOException
      Writes the barcode to an output stream in .PNG format.
      Parameters:
      formatName - The image format name, typically "png" (or "jpg").
      outputStream - The output stream that will receive the contents of the file image data of the barcode in the requested formatName.
      Throws:
      BarcodeException - If there are missing or invalid parameters assigned in this builder encountered during barcode encoding.
      IOException - For I/O errors writing the file.

    • toFile

      public File toFile(File pngFile) throws BarcodeException, IOException
      Writes the barcode to a file in .PNG format.
      Parameters:
      pngFile - The file, should have the ".png" file extension (but this is not checked).
      Returns:
      The file written.
      Throws:
      BarcodeException - If there are missing or invalid parameters assigned in this builder encountered during barcode encoding.
      IOException - For I/O errors writing the file.

    • toFile

      public File toFile(String formatName, File file) throws BarcodeException, IOException
      Writes the barcode to a file in the requested formatName such as "png" or "jpg".
      Parameters:
      formatName - The image format name, typically "png" (or "jpg").
      file - The file, should have the appropriate file extension such as "dot" + formatName.
      Returns:
      The file written.
      Throws:
      BarcodeException - If there are missing or invalid parameters assigned in this builder encountered during barcode encoding.
      IOException - For I/O errors writing the file.

    • getParamsString

      public String getParamsString()
      Gets the parameters as a string as:
       
   format=type,text=contents,width=w,height=h,...
      Returns:
      A string representation of set parameters.

    • toString

      public String toString()
      Returns a string representation of this instance.
      Overrides:
      toString in class Object
      Returns:
      A string as className[param1=nn,param2=nnn,...].

    • equals

      public boolean equals(Object obj)
      Checks if two builders are equal.
      Overrides:
      equals in class Object
      Parameters:
      obj - The object to compare with.
      Returns:
      true If the builders are equal.

    • hashCode

      public int hashCode()
      Gets the hashcode of this builder.
      Overrides:
      hashCode in class Object
      Returns:
      The hashcode.

    • clone

      public BarcodeBuilder clone()
      Clones this instance. This method can be used to clone a builder in order to e.g. add parameters and not to modify the first builder.
      Overrides:
      clone in class Object
      Returns:
      The cloned BarcodeBuilder.

    • getBarcodeType

      public BarcodeType getBarcodeType()
      Gets the barcode type or format.
      Returns:
      The BarcodeType.

    • isValidating

      public boolean isValidating()
      Returns if the validation mode is enabled.
      Returns:
      The validation enabled flag.

    • getText

      public String getText()
      Gets the current barcode text contents.
      Returns:
      The text, or null if not set.

    • getWidth

      public int getWidth()
      Gets the width of the barcode.
      Returns:
      The requested width, or zero if not set or for smallest width.

    • getHeight

      public int getHeight()
      Gets the height of the barcode.
      Returns:
      The requested height, or zero if not set or for smallest height.

    • getErrorCorrection

      public ErrorCorrectionLevel getErrorCorrection()
      Gets the QR code error correction level.
      Returns:
      The error correction level, or null if not set or default Low (ErrorCorrectionLevel.L = ~7%) or this barcode type is not a QR code.

    • getHints

      public Map<EncodeHintType,?> getHints()
      Gets a copy of the hints used for the Zxing barcode encoder.
      Returns:
      A map of hints, or null if none are set.