Class JsonValueSafety

java.lang.Object
org.apache.juneau.commons.utils.JsonValueSafety

public final class JsonValueSafety extends Object
Bounded, iterative walker that validates already-materialized JSON values against structural safety limits.

This helper defends against pathological inputs (excessive nesting, unbounded node counts, cyclic references, and runaway traversal times) before a value is serialized or otherwise consumed. It walks only in-memory maps, collections, arrays, and scalar leaves; it never resolves "$ref" or performs any I/O.

All violations are reported as neutral IllegalArgumentExceptions. Typed or adaptor callers are responsible for mapping these to the appropriate JSON-RPC error code, which keeps this core class free of any revision-specific error policy.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Maximum allowed nesting depth of the walked value.
    static final int
    Maximum allowed number of distinct nodes (containers and leaves) in the walked value.
    static final long
    Maximum allowed wall-clock time, in milliseconds, for a single traversal.
    static final long
    Deadline value meaning "no wall-clock limit": the depth, node-count and cycle bounds still apply.
  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    check(Object value, String label)
    Validates the specified value against the structural safety limits using a fresh deadline.
    static void
    check(Object root, String label, long deadlineNanos)
    Validates the specified value against the structural safety limits using the specified traversal deadline.
    static long
    Computes a fresh traversal deadline from the current time.
    static long
    remainingNanos(long deadlineNanos)
    Computes the number of nanoseconds remaining before the specified deadline.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • MAX_DEPTH

      public static final int MAX_DEPTH
      Maximum allowed nesting depth of the walked value.
      See Also:
    • MAX_NODES

      public static final int MAX_NODES
      Maximum allowed number of distinct nodes (containers and leaves) in the walked value.
      See Also:
    • MAX_TRAVERSAL_MILLIS

      public static final long MAX_TRAVERSAL_MILLIS
      Maximum allowed wall-clock time, in milliseconds, for a single traversal.
      See Also:
    • NO_DEADLINE

      public static final long NO_DEADLINE
      Deadline value meaning "no wall-clock limit": the depth, node-count and cycle bounds still apply.

      Use this for server-authored or already size-bounded values, where a slow walk (a loaded host, a GC pause) must not be reported as a violation.

      See Also:
  • Method Details

    • deadlineNanos

      public static long deadlineNanos()
      Computes a fresh traversal deadline from the current time.
      Returns:
      An absolute deadline in System.nanoTime() units, MAX_TRAVERSAL_MILLIS milliseconds in the future.
    • check

      public static void check(Object value, String label)
      Validates the specified value against the structural safety limits using a fresh deadline.
      Parameters:
      value - The value to walk. Can be null, in which case this method returns immediately.
      label - A human-readable label describing the value; used as a prefix in violation messages.
      Throws:
      IllegalArgumentException - If the value violates any of the depth, node-count, traversal-time, or JSON-shape constraints.
    • check

      public static void check(Object root, String label, long deadlineNanos)
      Validates the specified value against the structural safety limits using the specified traversal deadline.
      Parameters:
      root - The value to walk. Can be null, in which case this method returns immediately.
      label - A human-readable label describing the value; used as a prefix in violation messages.
      deadlineNanos - An absolute deadline in System.nanoTime() units after which the traversal is aborted.
      Throws:
      IllegalArgumentException - If the value exceeds MAX_DEPTH, exceeds MAX_NODES, exceeds the traversal deadline, contains a non-string JSON object key, or contains a leaf that is not a JSON value type (String, Number, or Boolean).
    • remainingNanos

      public static long remainingNanos(long deadlineNanos)
      Computes the number of nanoseconds remaining before the specified deadline.
      Parameters:
      deadlineNanos - An absolute deadline in System.nanoTime() units.
      Returns:
      The remaining nanoseconds, or 0 if the deadline has already passed.