Package com.digimarc.dms.payload

Class Payload

java.lang.Object
com.digimarc.dms.payload.Payload
Direct Known Subclasses:
RawPayload
public class Payload extends Object
This class contains the data and possible representations that resulted from an image or audio detection.

The BaseReader.Symbology property reveals the type of item detected and contained in the Payload. This can help inform the developer if the detection was a Digimarc Barcode, a traditional 1D barcode, or a QR Code and handle each payload accordingly. For example, the developer may want to use the Resolver to resolve Digimarc Barcodes but may want to open QR Code contents directly within the app: 


 BaseReader.Symbology symbology = payload.getSymbology();
 if (symbology.equals(BaseReader.ImageSymbology.Image_Digimarc)) {
      // Resolve
 } else if (symbology.equals(BaseReader.ImageSymbology.Image_QRCode)) {
      // Open contents
 }

The best way for an application to access payload data is via the Payload.Representation object. Representations allow an app to request data in the format that it wants to handle. For instance, if an app wants to process UPCA barcodes then it can request the BasicRepresentation.UPC_A representation. If the payload can be represented that way then a string containing the UPCA code value will be returned, otherwise null. It doesn't matter what code type this data came from, whether it was an actual UPCA barcode, a Digimarc Barcode or something else entirely. If the data can be represented as a UPCA barcode then it will be returned that way. 


  String upcaRepresentation = (String) payload.getRepresentation(Payload.BasicRepresentation.UPC_A);
  if (upcaRepresentation != null) {
         // upcaRepresentation contains a UPCA value
  }

The most frequently used representation types can be found in the Payload.BasicRepresentation enumeration. Some specific representations for GS1 AIs can be found in the Payload.GS1_AI_Representation. Most applications will not have a need to use the specialized representations.

Payload also carries any applicable GS1 Application Identifiers (AIs), which can be queried through the GS1 map as shown below. In general we recommend accessing GS1 AI data directly via the getGS1Data() method rather than using Payload.GS1_AI_Representation. 


 String gtin14AI = "01";
 Map<String, String> aiMap = payload.getGS1Data();
 if (aiMap.containsKey("01")) {
      // aiMap contains a GTIN-14 value
 }

  • Constructor Details

    • Payload

      public Payload(@NonNull String cpmPath)
      Constructor.
      Parameters:
      cpmPath - The CPM path of the payload.

  • Method Details

    • getPayloadString

      @NonNull public String getPayloadString()
      Gets the CPM path of the payload.
      Returns:
      Payload contents as a CPM path string.

    • getSymbology

      @NonNull public BaseReader.Symbology getSymbology()
      Gets the symbology ID of the detector that decoded this payload. This method can be used to determine how a payload should be handled by the application.
      Returns:
      A symbology ID from the enum set defined by BaseReader.ImageSymbology, BaseReader.AudioSymbology and BaseReader.UndefinedSymbology.

    • equals

      public boolean equals(Object o)
      Check equality of two payload objects. This method should not be used if either payload in the comparison is ephemeral. See isEphemeral() for more information.
      Overrides:
      equals in class Object
      Parameters:
      o - Object to compare against
      Returns:
      Returns true if the CPM paths of the two objects match, false otherwise.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getRepresentation

      @Nullable public Object getRepresentation(@NonNull Payload.Representation representation)
      Retrieves a string representation of the payload value in the requested format. Note that many payloads are only available in specific representations.
      Parameters:
      representation - The requested representation type from Payload.BasicRepresentation, Payload.Sgtin96Representation, Payload.GS1_AI_Representation or Payload.GIAIFieldRepresentation.
      Returns:
      Returns a string containing the payload in the requested representation. Returns null if the representation is invalid for this payload.

    • getAllRepresentations

      @NonNull public Map<Payload.Representation,Object> getAllRepresentations()
      Gets all valid representations of the current payload and returns it within a Map of Representations to string values. For each representation within the map the app can get the Key value and call Payload.Representation.getName() on it to get a string name of the representation type.
      Returns:
      Returns a Map object containing Representations and their string values. If no representations are valid for the payload then an empty Map will be returned.

    • isEphemeral

      public boolean isEphemeral()
      Is this payload value ephemeral or is it stable across reader sessions? Some watermarks, like the Digimarc Secure Digital Watermark, return ephemeral payload values. These values may change between reader sessions and must be resolved with the Digimarc Resolver to obtain stable results. Ephemeral payloads should not be compared using the equals(Object) method as the result will not be consistant.
      Returns:
      True if this is an ephemeral value, false otherwise.

    • getData

      @Nullable public Payload.Data getData(Payload.DataFormatMode mode)
      Gets the payload data and a representation describing its format.

      Note that in most cases, Payload.DataFormatMode.Compatible provides sufficient information. Payload.DataFormatMode.Native is usually more useful to developers who prefer handling results as GS1 element strings.

      Parameters:
      mode - Format to return data in.
      Returns:
      Data in the requested format or null if the payload is invalid or unsupported.

    • getData

      @Nullable public Payload.Data getData()
      Gets the payload data and a representation describing its format. This method returns the data in Compatible format mode.
      Returns:
      Data in the Compatible format or null if the payload is invalid or unsupported.

    • getGS1Data

      @NonNull public Map<String,String> getGS1Data()
      Gets all GS1 data fields from the payload. This is returned as a map of AI and value strings. Note that invalid AI entries within the payload will be excluded from the returned data. The term "invalid" here refers to AI/value entries that don't conform to the GS1 spec. Specifically, the GS1 spec states that while AIs may appear more than once in a GS1 encoded string the values must be the same for each occurrence (GS1 Specification section 4.14).

      Note that these checks are performed only on the individual AIs and values within the string. No checks are performed as to the overall validity of the GS1 string (i.e. required fields when certain AIs are present, AIs that can't appear together, etc).

      Returns:
      A map of all valid AIs and values within the payload. If no valid AIs are present an empty map will be returned.