Package com.iizix.barcode

Class BarcodeBuilder

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    public final class BarcodeBuilder
extends java.lang.Object
implements java.lang.Cloneable, java.io.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:
    Serialized Form

    • Method Detail

      • 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​(java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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​(java.lang.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.

      • 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.

      • 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.

      • asURNString

        public java.lang.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 java.lang.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 java.awt.image.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​(java.io.OutputStream pngOutputStream)
                    throws BarcodeException,
                           java.io.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.
        java.io.IOException - For I/O errors writing the file.

      • toOutputStream

        public void toOutputStream​(java.lang.String formatName,
                           java.io.OutputStream outputStream)
                    throws BarcodeException,
                           java.io.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.
        java.io.IOException - For I/O errors writing the file.

      • toFile

        public java.io.File toFile​(java.io.File pngFile)
                    throws BarcodeException,
                           java.io.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.
        java.io.IOException - For I/O errors writing the file.

      • toFile

        public java.io.File toFile​(java.lang.String formatName,
                           java.io.File file)
                    throws BarcodeException,
                           java.io.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.
        java.io.IOException - For I/O errors writing the file.

      • getParamsString

        public java.lang.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 java.lang.String toString()
        Returns a string representation of this instance.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string as className[param1=nn,param2=nnn,...].

      • equals

        public boolean equals​(java.lang.Object obj)
        Checks if two builders are equal.
        Overrides:
        equals in class java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.util.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.