Class BarcodeBuilder
- java.lang.Object
- com.iizix.barcode.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 thesize
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 Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.awt.image.BufferedImage
asBufferedImage()
Creates a BufferedImage of the barcode that can be used in java.awt transformations or other operations.java.lang.String
asSVG()
Creates an SVG image for the barcode.BarcodeURN
asURN()
Gets the String to as a{@link BarcodeURN}
for this barcode.java.lang.String
asURNString()
Gets the String to as a{@link BarcodeURN}
for this barcode.BarcodeBuilder
charset(java.lang.String charsetName)
Specifies what character set to use for encoding valid for the barcode types or formatsBarcodeType.AZTEC
,BarcodeType.PDF_417
andBarcodeType.QR_CODE
.BarcodeBuilder
charset(java.nio.charset.Charset charset)
Specifies what character set to use for encoding valid for the barcode types or formatsBarcodeType.AZTEC
,BarcodeType.PDF_417
andBarcodeType.QR_CODE
.BarcodeBuilder
checkParams()
Checks the basic parameters, regardless of if validation mode is enabled or not.BarcodeBuilder
clone()
Clones this instance.BarcodeBuilder
compact(boolean compact)
Sets whether to use compact mode forBarcodeType.PDF_417
barcodes.BarcodeBuilder
compaction(Compaction compaction)
Sets whether to use compaction mode forBarcodeType.PDF_417
barcodes.BarcodeBuilder
dimensions(int minCols, int maxCols, int minRows, int maxRows)
Sets the dimensions for a PDF417 barcode, i.e.boolean
equals(java.lang.Object obj)
Checks if two builders are equal.BarcodeBuilder
errorCorrection(int errorCorrectionLevel)
Assigns the error correction for a AZTEC or PDF417 barcodes.BarcodeBuilder
errorCorrection(ErrorCorrectionLevel errorCorrectionLevel)
Assigns the error correction for a QR code.BarcodeType
getBarcodeType()
Gets the barcode type or format.ErrorCorrectionLevel
getErrorCorrection()
Gets the QR code error correction level.int
getHeight()
Gets the height of the barcode.java.util.Map<EncodeHintType,?>
getHints()
Gets a copy of the hints used for the Zxing barcode encoder.java.lang.String
getParamsString()
Gets the parameters as a string as:java.lang.String
getText()
Gets the current barcode text contents.int
getWidth()
Gets the width of the barcode.int
hashCode()
Gets the hashcode of this builder.boolean
isValidating()
Returns if the validation mode is enabled.BarcodeBuilder
layers(int number)
Specifies the required number of layers for anBarcodeType.AZTEC
barcode.BarcodeBuilder
margin(int margin)
Sets the margin in pixels to use when generating the barcode, the meaning can vary by format.BarcodeBuilder
shape(SymbolShapeHint shape)
Specifies the matrix shape for Data Matrix.BarcodeBuilder
size(int size)
Assigns the size for a as the width and height, typically used for a 2-dimensional barcode such asBarcodeType.AZTEC
,BarcodeType.DATA_MATRIX
andBarcodeType.QR_CODE
.BarcodeBuilder
size(int width, int height)
Assigns the width and height for the barcode.BarcodeBuilder
text(java.lang.String text)
Assign the text contents for the barcode.java.io.File
toFile(java.io.File pngFile)
Writes the barcode to a file in .PNG format.java.io.File
toFile(java.lang.String formatName, java.io.File file)
Writes the barcode to a file in the requestedformatName
such as "png" or "jpg".void
toOutputStream(java.io.OutputStream pngOutputStream)
Writes the barcode to an output stream in .PNG format.void
toOutputStream(java.lang.String formatName, java.io.OutputStream outputStream)
Writes the barcode to an output stream in .PNG format.java.lang.String
toString()
Returns a string representation of this instance.BarcodeBuilder
validate(boolean isEnabled)
Turns validation mode on or off.BarcodeBuilder
version(int number)
Specifies the exact version of QR code to be encoded.
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 thetext
isnull
.BarcodeValidationException
- If thetext
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 asBarcodeType.AZTEC
,BarcodeType.DATA_MATRIX
andBarcodeType.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 thesize
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 thesize
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 notBarcodeType.QR_CODE
, then this method will do nothing.- Parameters:
errorCorrectionLevel
- The error correction level, ornull
to reset to the defaultErrorCorrectionLevel.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 aBarcodeType.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 notBarcodeType.AZTEC
orBarcodeType.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 theerrorCorrectionLevel
value is out of range for the barcode type or format.BarcodeValidationException
- If this barcode type or format is not aBarcodeType.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 formatsBarcodeType.AZTEC
,BarcodeType.PDF_417
andBarcodeType.QR_CODE
. If validation mode is enabled for these barcode type or format, aBarcodeValidationException
is thrown, otherwise this method will do nothing.- Parameters:
charsetName
- The character set name, ornull
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 aBarcodeType.AZTEC
,BarcodeType.PDF_417
orBarcodeType.QR_CODE
and validation mode is enabled, or if it is one of these barcode types or formats and thecharsetName
is illegal or unsupported in this Java VM.
charset
public BarcodeBuilder charset(java.nio.charset.Charset charset)
Specifies what character set to use for encoding valid for the barcode types or formatsBarcodeType.AZTEC
,BarcodeType.PDF_417
andBarcodeType.QR_CODE
. If validation mode is enabled for these barcode type or format, aBarcodeValidationException
is thrown, otherwise this method will do nothing.- Parameters:
charset
- The character set, ornull
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 aBarcodeType.AZTEC
,BarcodeType.PDF_417
orBarcodeType.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 formatBarcodeType.DATA_MATRIX
supports this method. If validation mode is enabled and the barcode is not DATA_MATRIX, aBarcodeValidationException
is thrown, otherwise this method will do nothing.- Parameters:
shape
- The shape, ornull
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 aBarcodeType.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
andBarcodeType.QR_CODE
. For other formats, this method will do nothing unless validation mode is enabled in which case aBarcodeValidationException
is thrown.All supported barcode formats or types:
BarcodeType.CODABAR
,BarcodeType.CODE_39
,BarcodeType.CODE_93
,BarcodeType.CODE_128
,BarcodeType.EAN_13
,BarcodeType.ITF
,BarcodeType.PDF_417
,BarcodeType.QR_CODE
,BarcodeType.UPC_A
,BarcodeType.UPC_E
.
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 forBarcodeType.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 isfalse
.- Returns:
- This instance in order to be able to concatenate methods for this builder.
- Throws:
BarcodeValidationException
- If this barcode type or format is notBarcodeType.PDF_417
and validation mode is enabled.
compaction
public BarcodeBuilder compaction(Compaction compaction)
Sets whether to use compaction mode forBarcodeType.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, ornull
to reset to defaultCompaction.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 notBarcodeType.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 notBarcodeType.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 anBarcodeType.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 notBarcodeType.AZTEC
ornumber
is less than-4
or larger than32
.
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 notBarcodeType.QR_CODE
or versionnumber
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 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 requestedformatName
.- 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 requestedformatName
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 classjava.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 classjava.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 classjava.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 classjava.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.