Package com.smartgwt.client.util

# Class JSON

java.lang.Object
com.smartgwt.client.util.JSON

public class JSON extends Object
Utilities for working with JSON data.

### Native JSON.stringify() vs isc.JSON.encode()

For maximum performance when serializing large datasets, consider using the native `JSON.stringify()` when your data meets certain criteria. Native serialization is approximately 6-10x faster than `isc.JSON.encode()`, but lacks several features that Smart GWT provides:

Use native `JSON.stringify()` when ALL of these conditions are met:

- Data contains no circular references - native throws an error on cycles rather than handling them gracefully. If your data might have cycles (e.g., parent/child back-references in tree structures), you must use `isc.JSON.encode()`.
- Data contains no Date values, OR you accept JSON's default date handling. Native `JSON.stringify()` converts Dates to ISO 8601 strings (e.g., "2024-01-15T14:30:00.000Z"). This loses:
  - Logical Date distinction: Smart GWT's logical dates (date-only, no time component) are serialized identically to datetimes by native JSON
  - Logical Time distinction: Smart GWT's logical times (time-only, no date component) become full datetime strings
  - Timezone handling: Native always outputs UTC; Smart GWT can preserve local timezone context for logical dates/times
  Use `JSONEncoder.dateFormat` with values like "logicalDateConstructor" to preserve these distinctions when round-tripping data.
- Data contains no Smart GWT class instances - native JSON cannot serialize Smart GWT widgets or other framework objects meaningfully
- You do not need pretty-printed output - native JSON.stringify's optional formatting is less flexible than `JSONEncoder.prettyPrint`
- You do not need custom serialization via object `_serialize()` methods

Use `isc.JSON.encode()` when ANY of these apply:

- Data might contain circular references (automatically detected and handled)
- You need to preserve Smart GWT's logical date/time/datetime distinctions
- You're serializing Smart GWT components or class instances
- You need back-reference paths for reconstructing object graphs
- You want configurable date formats (`JSONDateFormat`)
- You need readable, pretty-printed output

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JSON()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static JavaScriptObject`
  `decode(String jsonString)`
  De-serialize an object from JSON.
  `static Map`
  `decodeSafe(String jsonString, Function jsonReviver)`
  Decodes strict JSON using native browser JSON parsing APIs.
  `static void`
  `decodeSafeWithDates(String jsonString)`
  Uses `decodeSafe()` to decode strict JSON using native browser JSON parsing APIs, with settings to correctly process formatted date values created with `JSONDateFormat` logicalDateConstructor.
  `static Map`
  `decodeStrict(String jsonString)`
  De-serialize an object from JSON, attempting native JSON.parse() first for performance, then falling back to eval() if the input contains Smart GWT pseudo-JSON extensions (unquoted keys, single quotes, trailing commas, etc.).
  `static String`
  `encode(JavaScriptObject object)`
  Serialize an object as a JSON string.
  `static String`
  `encode(JavaScriptObject object, JSONEncoder settings)`
  Serialize an object as a JSON string.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### JSON

    public JSON()

- ## Method Details

  - ### decodeSafe

    public static Map decodeSafe(String jsonString, Function jsonReviver)
    Decodes strict JSON using native browser JSON parsing APIs. This API will not work with pseudo-JSON that must be parsed as JavaScript (such as that produced by encoding with `JSONDateFormat` logicalDateConstructor).

    This API is called "safe" because using a JavaScript eval() to decode JSON is potentially unsafe if the data being decoded is untrusted. For example, if users are able to save data as JSON for other uses to see (such as sharing `ListGrid.viewState`) and there is no validation of the saved data to ensure safety and some users are untrusted, then saved JSON could be used similarly to an XSS attack, allowing one user to execute JavaScript code in another user's browser.

    Note that, because JSON has no way of representing dates, serializing a structure that contains dates and then deserializing with decodeSafe() necessarily results in any Dates becoming strings. Use `JSONDateFormat` "logicalDateString" in combination with `decodeSafeWithDates()` to round-trip date, time and datetime values accurately.

    Parameters:
      `jsonString` - JSON data to be de-serialized
      `jsonReviver` - optional setting
    Returns:
      object derived from JSON String

  - ### decodeSafeWithDates

    public static void decodeSafeWithDates(String jsonString)
    Uses `decodeSafe()` to decode strict JSON using native browser JSON parsing APIs, with settings to correctly process formatted date values created with `JSONDateFormat` logicalDateConstructor.
    Parameters:
      `jsonString` - JSON data to be de-serialized

  - ### decodeStrict

    public static Map decodeStrict(String jsonString)
    De-serialize an object from JSON, attempting native JSON.parse() first for performance, then falling back to eval() if the input contains Smart GWT pseudo-JSON extensions (unquoted keys, single quotes, trailing commas, etc.).

    This method is optimized for cases where the JSON is typically strict (conforming to the JSON spec) but may occasionally contain pseudo-JSON extensions. The native JSON.parse() fast path provides significant performance improvements in V8 and other modern engines.

    For data that is always strict JSON, use `decodeSafe()` instead.

    Parameters:
      `jsonString` - JSON or pseudo-JSON data to be de-serialized
    Returns:
      object derived from JSON String

  - ### encode

    public static String encode(JavaScriptObject object)
    Serialize an object as a JSON string.

    Automatically handles circular references - see `circularReferenceMode`.

    Note that using the String produced by this API with `JSON.decode` will not successfully preserve dates. Use `JSONEncoder.setDateFormat` "dateConstructor" to have dates round-trip properly.

    Because GWT does not support Java reflection, JSON encoding cannot discover the properties of an arbitrary Java POJO. The following objects are supported:

    - any primitive type (String, Date, Number, Boolean)
    - any Map or Collection in any level of nesting
    - DataClass (Record's superclass) and RecordList
    - any widget (see +link{JSONEncoder.serializeInstances})
    - JavaScriptObject
    - an Array containing any of the above
    Parameters:
      `object` - object to serialize
    Returns:
      object encoded as a JSON String

  - ### encode

    public static String encode(JavaScriptObject object, JSONEncoder settings)
    Serialize an object as a JSON string.

    Automatically handles circular references - see `circularReferenceMode`.

    Note that using the String produced by this API with `JSON.decode` will not successfully preserve dates. Use `JSONEncoder.setDateFormat` "dateConstructor" to have dates round-trip properly.

    Because GWT does not support Java reflection, JSON encoding cannot discover the properties of an arbitrary Java POJO. The following objects are supported:

    - any primitive type (String, Date, Number, Boolean)
    - any Map or Collection in any level of nesting
    - DataClass (Record's superclass) and RecordList
    - any widget (see +link{JSONEncoder.serializeInstances})
    - JavaScriptObject
    - an Array containing any of the above
    Parameters:
      `object` - object to serialize
      `settings` - optional settings for encoding
    Returns:
      object encoded as a JSON String

  - ### decode

    public static JavaScriptObject decode(String jsonString)
    De-serialize an object from JSON. Currently, this is simply a JavaScript eval() and should be used for trusted data only.
    Parameters:
      `jsonString` - JSON data to be de-serialized
    Returns:
      object derived from JSON String