Package com.ultikits.ultitools.utils

Class PayloadReader

java.lang.Object
com.ultikits.ultitools.utils.PayloadReader
@Internal public final class PayloadReader extends Object
Strict protocol payload reader shared by framework handlers; internal, not for module use. Validation failures are unchecked and carry invalid_message plus the request id; AgentMessageRouter converts them to correlated errors without exposing payload text. JSON values are copied on input and access. Bounds are inclusive and strings are measured in Unicode code points, as in the vendored JSON Schemas.
Since:
6.3.1

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final String
    id
     
    private final com.google.gson.JsonObject
    payload
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    PayloadReader(String id, com.google.gson.JsonObject payload)
    Creates a reader over a defensive payload snapshot.

  • Method Summary

    Modifier and Type
    Method
    Description
    com.google.gson.JsonArray
    array(String key, int min, int max)
    Reads a required array; element validation remains the caller's responsibility.
    boolean
    bool(String key)
    Reads a required boolean without string or number coercion.
    private BigDecimal
    decimal(String key)
     
    String
    enumValue(String key, String... values)
    Reads a required string matching exactly one allowed value.
    long
    integer(String key, long min, long max)
    Reads a required integral JSON number, rejecting fractional or overflowing values.
    private InvalidFrameException
    invalid()
     
    PayloadReader
    keys(String[] required, String... optional)
    Rejects missing required keys and every key outside the two sets.
    double
    number(String key, double min, double max)
    Reads a required finite JSON number without string coercion.
    com.google.gson.JsonObject
    object(String key)
    Reads a required object; its field validation remains the caller's responsibility.
    com.google.gson.JsonElement
    optional(String key)
    Reads an optional key without imposing a value type.
    com.google.gson.JsonElement
    required(String key)
    Reads a required key without imposing a value type.
    String
    string(String key, int min, int max, Pattern pattern)
    Reads a required string without coercion from other JSON types.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • id

      private final String id

    • payload

      private final com.google.gson.JsonObject payload

  • Constructor Details

    • PayloadReader

      public PayloadReader(String id, com.google.gson.JsonObject payload)
      Creates a reader over a defensive payload snapshot.
      Parameters:
      id - the request envelope ULID for validation errors
      payload - the non-null object to validate

  • Method Details

    • keys

      public PayloadReader keys(String[] required, String... optional)
      Rejects missing required keys and every key outside the two sets.
      Parameters:
      required - names that must be present, even when their value is JSON null
      optional - additional allowed names
      Returns:
      this reader; validate each value separately

    • required

      public com.google.gson.JsonElement required(String key)
      Reads a required key without imposing a value type.
      Parameters:
      key - the field name
      Returns:
      a deep copy, including JSON null when explicitly present

    • optional

      public com.google.gson.JsonElement optional(String key)
      Reads an optional key without imposing a value type.
      Parameters:
      key - the field name
      Returns:
      a deep copy, or Java null only when absent

    • string

      public String string(String key, int min, int max, Pattern pattern)
      Reads a required string without coercion from other JSON types.
      Parameters:
      key - the field name
      min - minimum code-point count
      max - maximum code-point count
      pattern - full-string pattern, or null to skip pattern validation
      Returns:
      the validated string

    • integer

      public long integer(String key, long min, long max)
      Reads a required integral JSON number, rejecting fractional or overflowing values.
      Parameters:
      key - the field name
      min - minimum allowed value
      max - maximum allowed value
      Returns:
      the validated integer

    • number

      public double number(String key, double min, double max)
      Reads a required finite JSON number without string coercion.
      Parameters:
      key - the field name
      min - minimum allowed value
      max - maximum allowed value
      Returns:
      the validated number

    • decimal

      private BigDecimal decimal(String key)

    • bool

      public boolean bool(String key)
      Reads a required boolean without string or number coercion.
      Parameters:
      key - the field name
      Returns:
      the validated boolean

    • enumValue

      public String enumValue(String key, String... values)
      Reads a required string matching exactly one allowed value.
      Parameters:
      key - the field name
      values - case-sensitive allowed values
      Returns:
      the validated enum value

    • array

      public com.google.gson.JsonArray array(String key, int min, int max)
      Reads a required array; element validation remains the caller's responsibility.
      Parameters:
      key - the field name
      min - minimum item count
      max - maximum item count
      Returns:
      a deep copy of the validated array

    • object

      public com.google.gson.JsonObject object(String key)
      Reads a required object; its field validation remains the caller's responsibility.
      Parameters:
      key - the field name
      Returns:
      a deep copy of the object

    • invalid

      private InvalidFrameException invalid()