Package org.gs1.gs1encoders

Class GS1Encoder

java.lang.Object
org.gs1.gs1encoders.GS1Encoder
public class GS1Encoder extends Object
Main class for processing GS1 barcode data, including validation, format conversion, and generation of outputs such as GS1 Digital Link URIs and Human-Readable Interpretation text.

  • Constructor Details

  • Method Details

    • getVersion

      public String getVersion()
      Get the version string of the library.

      Returns a string containing the version of the library, typically the build date.

      Returns:
      the version of the library

    • getSym

      public GS1Encoder.Symbology getSym()
      Get the current symbology type.

      This might be set manually via setSym(Symbology) or automatically when processing scan data with setScanData(String).

      Returns:
      the current symbology type
      See Also:

    • setSym

      public void setSym(GS1Encoder.Symbology value) throws GS1EncoderParameterException
      Set the symbology type.

      This allows the symbology to be specified as any one of the GS1Encoder.Symbology types.

      Parameters:
      value - the symbology type to set
      Throws:
      GS1EncoderParameterException - if an invalid symbology type is provided
      See Also:

    • getAddCheckDigit

      public boolean getAddCheckDigit()
      Get the current status of the "add check digit" mode for EAN/UPC and GS1 DataBar symbols.
      Returns:
      true if check digits will be generated automatically; false if the data must include a valid check digit
      See Also:

    • setAddCheckDigit

      public void setAddCheckDigit(boolean value) throws GS1EncoderParameterException
      Enable or disable "add check digit" mode for EAN/UPC and GS1 DataBar symbols.

      If false (default), then the data string must contain a valid check digit. If true, then the data string must not contain a check digit as one will be generated automatically.

      This option is only valid for symbologies that accept fixed-length data, specifically EAN/UPC and GS1 DataBar except Expanded (Stacked).

      Parameters:
      value - true to enable automatic check digit generation; false to require check digit in data
      Throws:
      GS1EncoderParameterException - if the value is invalid
      See Also:

    • getIncludeDataTitlesInHRI

      public boolean getIncludeDataTitlesInHRI()
      Get the status of the "include data titles in HRI" flag.

      Returns true if data titles should be included in HRI; otherwise false.

      Returns:
      the status of the "include data titles in HRI" flag

    • setIncludeDataTitlesInHRI

      public void setIncludeDataTitlesInHRI(boolean value) throws GS1EncoderParameterException
      Set the "include data titles in HRI" flag.

      When set to true, data titles from the GS1 General Specification will be included in the HRI text.

      Default: false

      Parameters:
      value - true to include data titles in HRI; false otherwise
      Throws:
      GS1EncoderParameterException - if an error occurs

    • getPermitUnknownAIs

      public boolean getPermitUnknownAIs()
      Get the status of the "permit unknown AIs" mode.

      Returns true if unknown AIs are permitted; otherwise false.

      Returns:
      the status of the "permit unknown AIs" mode

    • setPermitUnknownAIs

      public void setPermitUnknownAIs(boolean value) throws GS1EncoderParameterException
      Set the "permit unknown AIs" mode.

      If false (default), then all AIs represented by the input data must be known.

      If true, then unknown AIs (those not in this library's static AI table) will be accepted.

      Note: The option only applies to parsed input data, specifically bracketed AI data supplied with setAIdataStr(String) and GS1 Digital Link URIs supplied with setDataStr(String). Unbracketed AI element strings containing unknown AIs cannot be parsed because it is not possible to differentiate the AI from its data value when the length of the AI is uncertain.

      Default: false

      Parameters:
      value - true to permit unknown AIs; false otherwise
      Throws:
      GS1EncoderParameterException - if an error occurs

    • getPermitZeroSuppressedGTINinDLuris

      public boolean getPermitZeroSuppressedGTINinDLuris()
      Get the status of the "permit zero-suppressed GTINs in GS1 DL URIs" mode.

      Returns true if zero-suppressed GTINs are permitted in GS1 Digital Link URIs; otherwise false.

      Returns:
      the status of the "permit zero-suppressed GTINs in GS1 DL URIs" mode

    • setPermitZeroSuppressedGTINinDLuris

      public void setPermitZeroSuppressedGTINinDLuris(boolean value) throws GS1EncoderParameterException
      Set the status of the "permit zero-suppressed GTINs in GS1 DL URIs" mode.

      If false (default), then the value of a path component for AI (01) must be provided as a full GTIN-14.

      If true, then the value of a path component for AI (01) may contain the GTIN-14 with zeros suppressed, in the format of a GTIN-13, GTIN-12 or GTIN-8.

      This option only applies to parsed input data, specifically GS1 Digital Link URIs. Since zero-suppressed GTINs are deprecated, this option should only be enabled when it is necessary to accept legacy GS1 Digital Link URIs having zero-suppressed GTIN-14.

      Default: false

      Parameters:
      value - true to permit zero-suppressed GTINs; false otherwise
      Throws:
      GS1EncoderParameterException - if an error occurs

    • getValidationEnabled

      public boolean getValidationEnabled(GS1Encoder.Validation validation)
      Get the current enabled status of the provided AI validation procedure.
      Parameters:
      validation - a validation procedure to check the status of
      Returns:
      true if the AI validation procedure is currently enabled; false otherwise

    • setValidationEnabled

      public void setValidationEnabled(GS1Encoder.Validation validation, boolean value) throws GS1EncoderParameterException
      Enable or disable the given AI validation procedure.

      This determines whether certain checks are enforced when data is provided using setAIdataStr(String), setDataStr(String) or setScanData(String).

      If enabled is true (default), then the corresponding validation will be enforced. If enabled is false, then the corresponding validation will not be enforced.

      Note: The option only applies to AI input data.

      Parameters:
      validation - a validation procedure to set the enabled status of
      value - true to enable the validation; false to disable
      Throws:
      GS1EncoderParameterException - if an error occurs

    • getValidateAIassociations

      @Deprecated public boolean getValidateAIassociations()
      Deprecated.
      Use getValidationEnabled(Validation) instead
      Get the current enabled status of the GS1Encoder.Validation.RequisiteAIs validation procedure.

      Deprecated: Use getValidationEnabled(Validation) instead.

      This method is equivalent to calling getValidationEnabled(Validation) with the GS1Encoder.Validation.RequisiteAIs validation procedure.

      Returns:
      current status of the GS1Encoder.Validation.RequisiteAIs validation procedure

    • setValidateAIassociations

      @Deprecated public void setValidateAIassociations(boolean value) throws GS1EncoderParameterException
      Deprecated.
      Use setValidationEnabled(Validation, boolean) instead
      Enable or disable the GS1Encoder.Validation.RequisiteAIs validation procedure.

      Deprecated: Use setValidationEnabled(Validation, boolean) instead.

      This method is equivalent to calling setValidationEnabled(Validation, boolean) with the GS1Encoder.Validation.RequisiteAIs validation procedure.

      Parameters:
      value - true to enable the GS1Encoder.Validation.RequisiteAIs validation procedure; false to disable
      Throws:
      GS1EncoderParameterException - if an error occurs

    • getDataStr

      public String getDataStr()
      Get the raw data that would be directly encoded within a GS1 barcode message.

      This method reads the raw barcode data input buffer. The returned data represents the actual message content that would be encoded in the barcode symbol, including FNC1 characters represented as "^" for AI-based data.

      The returned string remains valid until subsequent calls to methods that modify the input data buffer such as setDataStr(String), setAIdataStr(String), or setScanData(String). If the content must persist beyond such calls, it should be copied to a separate variable.

      Returns:
      the raw barcode data input buffer, or null if no data has been set
      See Also:

    • setDataStr

      public void setDataStr(String value) throws GS1EncoderParameterException
      Set the raw data that would be directly encoded within a GS1 barcode message.

      A "^" character at the start of the input indicates that the data is in GS1 Application Identifier syntax. In this case, all subsequent instances of the "^" character represent the FNC1 non-data characters that are used to separate fields that are not specified as being pre-defined length from subsequent fields.

      Inputs beginning with "^" will be validated against certain data syntax rules for GS1 AIs. If the input is invalid then this method will throw a GS1EncoderParameterException. In the case that the data is unacceptable due to invalid AI content then a marked up version of the offending AI can be retrieved using getErrMarkup().

      Note: It is strongly advised that GS1 data input is instead specified using setAIdataStr(String) which takes care of the AI encoding rules automatically, including insertion of FNC1 characters where required. This can be used for all symbologies that accept GS1 AI syntax data.

      Inputs beginning with "http://" or "https://" will be parsed as a GS1 Digital Link URI during which the corresponding AI element string is extracted and validated.

      EAN/UPC, GS1 DataBar and GS1-128 support a Composite Component. The Composite Component must be specified in AI syntax. It must be separated from the primary linear components with a "|" character and begin with an FNC1 in first position, for example: 

       encoder.setDataStr("^0112345678901231|^10ABC123^11210630");

      The above specifies a linear component representing "(01)12345678901231" together with a composite component representing "(10)ABC123(11)210630".

      Note: For GS1 data it is simpler and less error prone to specify the input in human-friendly GS1 AI syntax using setAIdataStr(String).

      Parameters:
      value - the raw barcode data to be set
      Throws:
      GS1EncoderParameterException - if the provided data is invalid
      See Also:

    • getAIdataStr

      public String getAIdataStr()
      Get the barcode data input buffer in human-friendly GS1 AI syntax.

      Returns the barcode data in human-friendly GS1 AI syntax, or null if the input data does not contain AI data.

      Returns:
      the barcode data in GS1 AI syntax, or null if not AI data

    • setAIdataStr

      public void setAIdataStr(String value) throws GS1EncoderParameterException
      Set the barcode data input buffer using GS1 Application Identifier syntax.

      The input is provided in human-friendly format without FNC1 characters which are inserted automatically, for example: 

      (01)12345678901231(10)ABC123(11)210630

      This syntax harmonises the format for the input accepted by all symbologies. For example, the following input is acceptable for EAN-13, UPC-A, UPC-E, any variant of the GS1 DataBar family, GS1 QR Code and GS1 DataMatrix: 

      (01)00031234000054

      The input is immediately parsed and validated against certain rules for GS1 AIs, after which the resulting encoding for valid inputs is available via getDataStr(). If the input is invalid then an exception will be thrown.

      Any "(" characters in AI element values must be escaped as "\\(" to avoid conflating them with the start of the next AI.

      For symbologies that support a composite component (all except Data Matrix, QR Code, and DotCode), the data for the linear and 2D components can be separated by a "|" character, for example: 

      (01)12345678901231|(10)ABC123(11)210630
      Parameters:
      value - the barcode data in GS1 AI syntax
      Throws:
      GS1EncoderParameterException - if the input is invalid

    • getScanData

      public String getScanData()
      Get the expected scan data string that a reader should return.

      Returns the string that should be returned by scanners when reading a symbol that is an instance of the selected symbology and contains the same input data.

      The output will be prefixed with the appropriate AIM symbology identifier.

      Returns:
      the expected scan data string, or null if invalid

    • setScanData

      public void setScanData(String value) throws GS1EncoderScanDataException
      Process scan data received from a barcode reader.

      Process normalised scan data received from a barcode reader with reporting of AIM symbology identifiers enabled to extract the message data and perform syntax checks in the case of GS1 Digital Link and AI data input.

      This function will process scan data (such as the output of a barcode reader) and process the received data, setting the data input buffer to the message received and setting the selected symbology to something that is able to carry the received data.

      Note: In some instances the symbology determined by this library will not match that of the image that was scanned. The AIM symbology identifier prefix of the scan data does not always uniquely identify the symbology that was scanned. For example GS1-128 Composite symbols share the same symbology identifier as the GS1 DataBar family, and will therefore be detected as such.

      A literal "|" character may be included in the scan data to indicate the separation between the first and second messages that would be transmitted by a reader that is configured to return the composite component when reading EAN/UPC symbols.

      Example scan data input: 

      ]C1011231231231233310ABC123{GS}99TESTING
      where {GS} represents ASCII character 29.
      Parameters:
      value - the scan data string as read by a reader with AIM symbology identifiers enabled
      Throws:
      GS1EncoderScanDataException - if the scan data is invalid

    • getErrMarkup

      public String getErrMarkup()
      Get the error markup generated when parsing AI data fails due to a linting failure.

      When a setter function returns false (indicating an error), if that failure is due to AI-based data being invalid, a marked up instance of the AI that failed will be generated.

      Where it is meaningful to identify offending characters in the input data, these characters will be surrounded by "|" characters. Otherwise the entire AI value will be surrounded by "|" characters.

      Returns:
      marked up instance of the AI that failed validation, or empty string if no linting failure

    • getDLuri

      public String getDLuri(String stem) throws GS1EncoderDigitalLinkException
      Get a GS1 Digital Link URI that represents the AI-based input data.

      This method converts AI-based input data into a GS1 Digital Link URI format.

      Example: 

      (01)12345678901231(10)ABC123(11)210630
      with stem https://id.example.com/stem might produce: 
      https://id.example.com/stem/01/12345678901231?10=ABC123&11=210630
      Parameters:
      stem - a URI "stem" used as a prefix for the URI. If null, the GS1 canonical stem (https://id.gs1.org/) will be used
      Returns:
      a string representing the GS1 Digital Link URI for the input data
      Throws:
      GS1EncoderDigitalLinkException - if invalid input was provided

    • getHRI

      public String[] getHRI()
      Get the Human-Readable Interpretation ("HRI") text for the current data input buffer.

      For composite symbols, a separator "--" will be included in the array to distinguish between the linear and 2D components.

      Example output for ^011231231231233310ABC123|^99XYZ(TM) CORP: 

       (01) 12312312312333
 (10) ABC123
 --
 (99) XYZ(TM) CORP
      Returns:
      an array of strings representing the HRI text

    • getDLignoredQueryParams

      public String[] getDLignoredQueryParams()
      Get the non-numeric (ignored) query parameters from a GS1 Digital Link URI.

      For example, if the input data buffer contains: 

      https://a/01/12312312312333/22/ABC?name=Donald%2dDuck&99=ABC&testing&type=cartoon

      Then this method returns: name=Donald%2dDuck, testing, type=cartoon

      The returned strings are not URI decoded. The expected use for this method is to present which sections of a given GS1 Digital Link URI have been ignored.

      Returns:
      an array of strings containing the non-numeric query parameters that were ignored