Package com.cercalia.sdk.util

Class CercaliaResponseParser

java.lang.Object
com.cercalia.sdk.util.CercaliaResponseParser
public final class CercaliaResponseParser extends Object
Utility class for parsing Cercalia API JSON responses.

Cercalia's JSON format has several idiosyncrasies due to its XML heritage:

  • Attributes are prefixed with '@' (e.g., "@id").
  • Values can be primitive strings or objects with keys like "value" or "$valor".
  • Single-item lists are often returned as objects instead of arrays.
This class provides standard helpers to abstract away these inconsistencies.

  • Method Summary

    Modifier and Type
    Method
    Description
    static @Nullable com.fasterxml.jackson.databind.JsonNode
    getArrayElement(@Nullable com.fasterxml.jackson.databind.JsonNode node, int index)
    Get an element from an array node at the specified index.
    static int
    getArraySize(@Nullable com.fasterxml.jackson.databind.JsonNode node)
    Get the size of an array node, treating single objects as arrays of size 1.
    static @Nullable String
    getCercaliaAttr(@Nullable com.fasterxml.jackson.databind.JsonNode node, String key)
    Extract attribute value from Cercalia object.
    static @Nullable String
    getCercaliaValue(@Nullable com.fasterxml.jackson.databind.JsonNode node)
    Extract value from Cercalia value object.
    static boolean
    isArrayOrSingle(@Nullable com.fasterxml.jackson.databind.JsonNode node)
    Check if a JSON node represents an array or should be treated as one.
    static double
    parseCoordinate(@Nullable String value, String name)
    Parse a coordinate value from string to double.
    static @Nullable Double
    parseDoubleOrNull(@Nullable String value)
    Safely parse a double value, returning null if parsing fails.
    static @Nullable Integer
    parseIntOrNull(@Nullable String value)
    Safely parse an integer value, returning null if parsing fails.
    static @Nullable Long
    parseLongOrNull(@Nullable String value)
    Safely parse a long value, returning null if parsing fails.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • getCercaliaAttr

      @Nullable public static @Nullable String getCercaliaAttr(@Nullable @Nullable com.fasterxml.jackson.databind.JsonNode node, String key)
      Extract attribute value from Cercalia object. Handles both @attr and attr formats.
      Parameters:
      node - the JSON node to extract from.
      key - the attribute key (without @ prefix).
      Returns:
      the attribute value, or null if not found.

    • getCercaliaValue

      @Nullable public static @Nullable String getCercaliaValue(@Nullable @Nullable com.fasterxml.jackson.databind.JsonNode node)
      Extract value from Cercalia value object. Handles multiple formats: { "value": "..." }, { "$valor": "..." }, { "@value": "..." }, or plain string.
      Parameters:
      node - the JSON node to extract from.
      Returns:
      the value, or null if not found.

    • parseCoordinate

      public static double parseCoordinate(@Nullable @Nullable String value, String name)
      Parse a coordinate value from string to double. Throws an exception if the value is null (strict coordinates rule).
      Parameters:
      value - the string value to parse.
      name - the coordinate name (for error messages).
      Returns:
      the parsed double value.
      Throws:
      IllegalArgumentException - if value is null or invalid.

    • parseDoubleOrNull

      @Nullable public static @Nullable Double parseDoubleOrNull(@Nullable @Nullable String value)
      Safely parse a double value, returning null if parsing fails.
      Parameters:
      value - the string value to parse.
      Returns:
      the parsed Double, or null if parsing fails.

    • parseIntOrNull

      @Nullable public static @Nullable Integer parseIntOrNull(@Nullable @Nullable String value)
      Safely parse an integer value, returning null if parsing fails.
      Parameters:
      value - the string value to parse.
      Returns:
      the parsed Integer, or null if parsing fails.

    • parseLongOrNull

      @Nullable public static @Nullable Long parseLongOrNull(@Nullable @Nullable String value)
      Safely parse a long value, returning null if parsing fails.
      Parameters:
      value - the string value to parse.
      Returns:
      the parsed Long, or null if parsing fails.

    • isArrayOrSingle

      public static boolean isArrayOrSingle(@Nullable @Nullable com.fasterxml.jackson.databind.JsonNode node)
      Check if a JSON node represents an array or should be treated as one.
      Parameters:
      node - the JSON node to check.
      Returns:
      true if the node is an array or a single object.

    • getArraySize

      public static int getArraySize(@Nullable @Nullable com.fasterxml.jackson.databind.JsonNode node)
      Get the size of an array node, treating single objects as arrays of size 1.
      Parameters:
      node - the JSON node.
      Returns:
      the array size, or 0 if null.

    • getArrayElement

      @Nullable public static @Nullable com.fasterxml.jackson.databind.JsonNode getArrayElement(@Nullable @Nullable com.fasterxml.jackson.databind.JsonNode node, int index)
      Get an element from an array node at the specified index. Handles both array nodes and single object nodes.
      Parameters:
      node - the JSON node.
      index - the index.
      Returns:
      the element at the index, or null if out of bounds.