Package com.chilkatsoft.chilkat2

Class JsonObject

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.JsonObject
All Implemented Interfaces:
AutoCloseable
public class JsonObject extends ChilkatObject
<section class="jsonobject-summary">

Load, navigate, create, modify, search, sort, and emit JSON objects.

Chilkat.JsonObject provides DOM-style access to JSON objects. It can load, inspect, modify, create, search, sort, emit, and save JSON data. It supports path-based access, index-based member access, automatic creation of nested paths, object and array references, Firebase-style updates, record searches, date/time conversion, binary data encoding, variable substitution, and optional secure secret resolution.

Load and emit JSON

Load JSON from strings, files, buffers, or Chilkat objects, then emit the result as compact or pretty-formatted JSON.

Path-based navigation

Read and update nested values using JSON paths, with support for automatically creating missing object or array paths.

Member access

Access object members by name or index, inspect member types, retrieve values, and remove or rename members as needed.

Nested objects and arrays

Work directly with child JsonObject and JsonArray references to navigate and modify complex JSON structures.

Search and transform

Search records, sort object members, perform Firebase-style updates, and prepare JSON for API requests or application storage.

Special value handling

Handle date/time values, binary data encodings, exact numeric text, variable substitution, and secure secret resolution.

Common pattern: Load or create a JsonObject, navigate named members and nested paths, retrieve child arrays as JsonArray objects when ordered lists are encountered, update values as needed, then emit or save the final JSON. Use JsonObject for named JSON members and JsonArray for ordered lists.

For an extended overview, see JsonObject Class Overview.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Summary

    Constructors
    Constructor
    Description
    JsonObject()
    Creates a new JsonObject object.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addArrayAt​(int index, String name)
    Inserts a new JSON array member named name at the zero-based member position index.
    void
    addArrayCopyAt​(int index, String name, JsonArray jarr)
    Inserts a new JSON array member named name at the zero-based member position index.
    void
    addBoolAt​(int index, String name, boolean value)
    Inserts a new JSON boolean member named name at the zero-based member position index.
    void
    addIntAt​(int index, String name, int value)
    Inserts a new JSON number member named name at the zero-based member position index.
    void
    addNullAt​(int index, String name)
    Inserts a new JSON null member named name at the zero-based member position index.
    void
    addNumberAt​(int index, String name, String numericStr)
    Inserts a new JSON number member named name at the zero-based member position index.
    void
    addObjectAt​(int index, String name)
    Inserts a new JSON object member named name at the zero-based member position index.
    void
    addObjectCopyAt​(int index, String name, JsonObject jsonObj)
    Inserts a new JSON object member named name at the zero-based member position index.
    void
    addStringAt​(int index, String name, String value)
    Inserts a new JSON string member named name at the zero-based member position index.
    JsonArray
    appendArray​(String name)
    Appends a new JSON array member named name to this object.
    void
    appendArray2​(String name, JsonArray jarr)
    Appends a new JSON array member named name to this object.
    void
    appendArrayCopy​(String name, JsonArray jarr)
    Appends a new JSON array member named name to this object.
    void
    appendBool​(String name, boolean value)
    Appends a new JSON boolean member named name to this object.
    void
    appendInt​(String name, int value)
    Appends a new JSON number member named name to this object.
    JsonObject
    appendObject​(String name)
    Appends a new JSON object member named name to this object.
    void
    appendObject2​(String name, JsonObject jsonObj)
    Appends a new JSON object member named name to this object.
    void
    appendObjectCopy​(String name, JsonObject jsonObj)
    Appends a new JSON object member named name to this object.
    void
    appendString​(String name, String value)
    Appends a new JSON string member named name to this object.
    void
    appendStringArray​(String name, StringTable values)
    Appends a new JSON array member named name to this object.
    JsonArray
    arrayAt​(int index)
    Returns the JSON array stored in the member at zero-based position index.
    void
    arrayAt2​(int index, JsonArray jarr)
    Updates jarr to reference the JSON array stored at zero-based member position index and returns true on success.
    JsonArray
    arrayOf​(String jsonPath)
    Returns the JSON array at jsonPath.
    void
    arrayOf2​(String jsonPath, JsonArray jarr)
    Updates jarr to reference the JSON array at jsonPath and returns true on success.
    boolean
    boolAt​(int index)
    Returns the boolean value of the member at zero-based position index.
    boolean
    boolOf​(String jsonPath)
    Returns the boolean value at jsonPath.
    void
    bytesOf​(String jsonPath, String encoding, BinData bd)
    Reads the string value at jsonPath, decodes it using encoding (for example, base64 or hex), and appends the resulting bytes to bd.
    void
    clear()
    Removes all members from this JSON object, leaving an empty object equivalent to {}.
    void
    copyRef​(JsonObject jsonObj)
    Updates jsonObj so that it references the same JSON object as the caller.
    void
    dateOf​(String jsonPath, DateTime dt)
    Parses the date/time value at jsonPath and loads the result into dt.
    void
    delete​(String name)
    Deletes the direct member named name from this JSON object.
    void
    deleteAt​(int index)
    Deletes the member at zero-based position index.
    int
    deleteRecords​(String arrayPath, String relpath, String value, boolean caseSensitive)
    Deletes every object record in the array at arrayPath whose value at relative path relpath equals or wildcard-matches value.
    void
    dtOf​(String jsonPath, boolean bLocal, DtObj dt)
    Parses the date/time value at jsonPath into dt.
    String
    emit()
    Serializes the JSON document rooted at this object and returns the JSON text.
    void
    emitBd​(BinData bd)
    Serializes this JSON and appends the resulting bytes to bd.
    void
    emitSb​(StringBuilder sb)
    Serializes this JSON and appends the resulting text to sb.
    String
    emitWithSubs​(Hashtable subs, boolean omitEmpty)
    Serializes the JSON after substituting variables from subs into template strings.
    JsonObject
    findObjectWithMember​(String name)
    Recursively searches this JSON subtree for the first JSON object containing a direct member named name.
    void
    findObjectWithMember2​(String name, JsonObject jsonObj)
    Recursively searches this JSON subtree for the first object containing a direct member named name.
    JsonObject
    findRecord​(String arrayPath, String relPath, String value, boolean caseSensitive)
    Searches the JSON array at arrayPath for the first object whose value at relative path relPath equals or wildcard-matches value.
    void
    findRecord2​(String arrayPath, String relPath, String value, boolean caseSensitive, JsonObject jsonObj)
    Searches the JSON array at arrayPath using the same matching rules as FindRecord.
    String
    findRecordString​(String arrayPath, String relPath, String value, boolean caseSensitive, String retRelPath)
    Searches the JSON array at arrayPath for the first record whose relPath value equals or wildcard-matches value, then returns the value at retRelPath from that same record as a string.
    void
    firebaseApplyEvent​(String name, String data)
    Applies a Firebase Realtime Database event to this JSON object.
    void
    firebasePatch​(String jsonPath, String jsonData)
    Applies Firebase-style patch semantics at jsonPath.
    void
    firebasePut​(String jsonPath, String value)
    Applies Firebase-style put semantics at jsonPath, replacing or inserting the value at that path.
    String
    getDelimiterChar()
    Specifies the character used to separate object-member names in Chilkat JSON paths.
    JsonObject
    getDocRoot()
    Returns a JsonObject reference to the root object of the JSON document containing this object.
    void
    getDocRoot2​(JsonObject docRoot)
    Updates docRoot to reference the root object of the JSON document containing the caller and returns true on success.
    boolean
    getEmitCompact()
    Controls whether emitted JSON is compact or pretty-printed.
    boolean
    getEmitCrLf()
    Controls line endings when pretty-printed JSON is emitted (EmitCompact = false).
    boolean
    getEnableSecrets()
    Enables automatic resolution of Chilkat secret specification strings for supported string-setting methods.
    int
    getI()
    Supplies the integer substituted for i when a JSON path contains an array index such as [i].
    int
    getJ()
    Supplies the integer substituted for j when a JSON path contains [j].
    int
    getK()
    Supplies the integer substituted for k when a JSON path contains [k].
    boolean
    getLowerCaseNames()
    If true, member names are converted to lowercase while JSON is loaded by Load, LoadBd, LoadSb, or LoadFile.
    String
    getPathPrefix()
    Specifies a path prefix automatically prepended to JSON paths passed to path-based methods such as StringOf, ObjectOf, UpdateString, SetBoolOf, and SizeOfArray.
    int
    getSize()
    Returns the number of direct name/value members in this JSON object.
    boolean
    getStrict()
    When Strict is true, the Load methods first check that the data is well-formed JSON.
    String
    getUncommonOptions()
    Provides a catch-all string for uncommon, implementation-specific options.
    boolean
    hasMember​(String jsonPath)
    Returns true if a value exists at jsonPath; otherwise returns false.
    int
    indexOf​(String name)
    Returns the zero-based position of the direct member named name, or -1 if that member name is not found.
    int
    intAt​(int index)
    Returns the integer value of the member at zero-based position index.
    int
    intOf​(String jsonPath)
    Returns the integer value at jsonPath.
    boolean
    isNullAt​(int index)
    Returns true if the member at zero-based position index has the JSON value null; otherwise returns false.
    boolean
    isNullOf​(String jsonPath)
    Returns true if the value at jsonPath is the JSON literal null; otherwise returns false.
    int
    jsonTypeOf​(String jsonPath)
    Returns an integer identifying the JSON type of the value at jsonPath.
    void
    load​(String json)
    Parses the JSON text in json and loads the parsed data into this object for DOM-style access and modification.
    void
    loadBd​(BinData bd)
    Parses JSON from the bytes contained in bd and loads it into this object.
    void
    loadFile​(String path)
    Reads JSON text from the file at path, parses it, and loads the result into this object.
    void
    loadPredefined​(String name)
    Loads this object from the predefined JSON document identified by name.
    void
    loadSb​(StringBuilder sb)
    Parses JSON from the current contents of sb and loads it into this object.
    void
    makeCopy​(JsonObject json)
    Copies this JSON object into json.
    void
    moveMember​(int fromIndex, int toIndex)
    Moves the direct member at zero-based position fromIndex to toIndex.
    String
    nameAt​(int index)
    Returns the name of the member at zero-based position index.
    void
    newArrayOf​(String path, String jArr)
    Creates a JSON array at path and loads that array from the JSON text in jArr.
    void
    newObjectOf​(String path, String jObj)
    Creates a JSON object at path and loads that object from the JSON text in jObj.
    JsonObject
    objectAt​(int index)
    Returns the JSON object stored in the member at zero-based position index.
    void
    objectAt2​(int index, JsonObject jsonObj)
    Updates jsonObj to reference the JSON object stored at zero-based member position index and returns true on success.
    JsonObject
    objectOf​(String jsonPath)
    Returns the JSON object at jsonPath.
    void
    objectOf2​(String jsonPath, JsonObject jsonObj)
    Updates jsonObj to reference the JSON object at jsonPath and returns true on success.
    void
    predefine​(String name)
    Stores this JSON document in Chilkat's internal global collection of predefined JSON documents under name.
    void
    rename​(String oldName, String newName)
    Renames the direct member oldName to newName.
    void
    renameAt​(int index, String name)
    Renames the member at zero-based position index to name.
    void
    setBoolAt​(int index, boolean value)
    Sets the member at zero-based position index to a JSON boolean value.
    void
    setBoolOf​(String jsonPath, boolean value)
    Sets the value at jsonPath to a JSON boolean value.
    void
    setDelimiterChar​(String value)
    Sets the DelimiterChar property; see getDelimiterChar().
    void
    setEmitCompact​(boolean value)
    Sets the EmitCompact property; see getEmitCompact().
    void
    setEmitCrLf​(boolean value)
    Sets the EmitCrLf property; see getEmitCrLf().
    void
    setEnableSecrets​(boolean value)
    Sets the EnableSecrets property; see getEnableSecrets().
    void
    setI​(int value)
    Sets the I property; see getI().
    void
    setIntAt​(int index, int value)
    Sets the member at zero-based position index to a JSON number value.
    void
    setIntOf​(String jsonPath, int value)
    Sets the value at jsonPath to an integer JSON number.
    void
    setJ​(int value)
    Sets the J property; see getJ().
    void
    setK​(int value)
    Sets the K property; see getK().
    void
    setLowerCaseNames​(boolean value)
    Sets the LowerCaseNames property; see getLowerCaseNames().
    void
    setNullAt​(int index)
    Sets the member at zero-based position index to a JSON null value.
    void
    setNullOf​(String jsonPath)
    Sets the value at jsonPath to a JSON null value.
    void
    setNumberAt​(int index, String value)
    Sets the member at zero-based position index to a JSON number value.
    void
    setNumberOf​(String jsonPath, String value)
    Sets the value at jsonPath to a JSON number value.
    void
    setPathPrefix​(String value)
    Sets the PathPrefix property; see getPathPrefix().
    void
    setStrict​(boolean value)
    Sets the Strict property; see getStrict().
    void
    setStringAt​(int index, String value)
    Sets the member at zero-based position index to a JSON string value.
    void
    setStringOf​(String jsonPath, String value)
    Sets the value at jsonPath to a JSON string value.
    void
    setUncommonOptions​(String value)
    Sets the UncommonOptions property; see getUncommonOptions().
    int
    sizeOfArray​(String jsonPath)
    Returns the number of elements in the JSON array at jsonPath.
    void
    sort​(boolean ascending, boolean caseSensitive)
    Sorts this object's direct members by member name.
    String
    stringAt​(int index)
    Returns the string value of the member at zero-based position index.
    String
    stringOf​(String jsonPath)
    Returns the value at jsonPath as text.
    boolean
    stringOfEquals​(String jsonPath, String value, boolean caseSensitive)
    Returns true if the textual value at jsonPath equals value according to the caseSensitive setting; otherwise returns false.
    void
    stringOfSb​(String jsonPath, StringBuilder sb)
    Retrieves the value at jsonPath as text and appends it to sb.
    void
    swap​(int index1, int index2)
    Swaps the positions of the direct members at zero-based indexes index1 and index2.
    int
    typeAt​(int index)
    Returns an integer identifying the JSON type of the member at zero-based position index.
    long
    uIntOf​(String jsonPath)
    Returns the unsigned integer value at jsonPath.
    void
    updateBd​(String jsonPath, String encoding, BinData bd)
    Updates the value at jsonPath to a JSON string value, or creates the member and any missing path components as needed.
    void
    updateBool​(String jsonPath, boolean value)
    Updates the value at jsonPath to a JSON boolean value, or creates the member and any missing path components as needed.
    void
    updateInt​(String jsonPath, int value)
    Updates the value at jsonPath to a JSON number value, or creates the member and any missing path components as needed.
    void
    updateNewArray​(String jsonPath)
    Creates or replaces the value at jsonPath with a new empty JSON array.
    void
    updateNewObject​(String jsonPath)
    Creates or replaces the value at jsonPath with a new empty JSON object.
    void
    updateNull​(String jsonPath)
    Updates the value at jsonPath to a JSON null value, or creates the member and any missing path components as needed.
    void
    updateNumber​(String jsonPath, String numericStr)
    Updates the value at jsonPath to a JSON number value, or creates the member and any missing path components as needed.
    void
    updateSb​(String jsonPath, StringBuilder sb)
    Updates the value at jsonPath to a JSON string value, or creates the member and any missing path components as needed.
    void
    updateString​(String jsonPath, String value)
    Updates the value at jsonPath to a JSON string value, or creates the member and any missing path components as needed.
    void
    updateUInt​(String jsonPath, long value)
    Updates the value at jsonPath to a JSON number value, or creates the member and any missing path components as needed.
    void
    writeFile​(String path)
    Serializes this JSON and writes it to the file at path.

    Methods inherited from class com.chilkatsoft.chilkat2.ChilkatObject

    close, getDebugLogFilePath, getLastErrorHtml, getLastErrorText, getLastErrorXml, getLastMethodSuccess, getVerboseLogging, getVersion, isClosed, setDebugLogFilePath, setLastMethodSuccess, setVerboseLogging, toString

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • JsonObject

      public JsonObject()
      Creates a new JsonObject object.

  • Method Details

    • getDelimiterChar

      public String getDelimiterChar()
      Specifies the character used to separate object-member names in Chilkat JSON paths. The default is .. Set it to / for Firebase-style paths. This property should contain exactly one character.

      Arrays in paths: Array indexes continue to use square brackets, such as orders[0].id. If a member name itself contains a path-separator character, quote that path component with double quotes.

      Returns:
      the value of the DelimiterChar property

    • setDelimiterChar

      public void setDelimiterChar​(String value)
      Sets the DelimiterChar property; see getDelimiterChar().
      Parameters:
      value - the new value (not null)

    • getEmitCompact

      public boolean getEmitCompact()
      Controls whether emitted JSON is compact or pretty-printed. The default is true.

      true Emit a compact representation with no extra formatting whitespace.

      false Emit indented, human-readable JSON.

      JSON semantics: Formatting whitespace does not change the JSON data. Use compact output for transport/storage and pretty output for diagnostics or human review.

      Returns:
      the value of the EmitCompact property

    • setEmitCompact

      public void setEmitCompact​(boolean value)
      Sets the EmitCompact property; see getEmitCompact().
      Parameters:
      value - the new value

    • getEmitCrLf

      public boolean getEmitCrLf()
      Controls line endings when pretty-printed JSON is emitted (EmitCompact = false). The default is true.

      true Use CRLF line endings.

      false Use LF line endings.

      Compact output: This setting has no effect when EmitCompact is true because compact JSON is emitted without formatting line breaks.

      Returns:
      the value of the EmitCrLf property

    • setEmitCrLf

      public void setEmitCrLf​(boolean value)
      Sets the EmitCrLf property; see getEmitCrLf().
      Parameters:
      value - the new value

    • getEnableSecrets

      public boolean getEnableSecrets()
      Enables automatic resolution of Chilkat secret specification strings for supported string-setting methods. The default is false. When enabled, a value beginning with !! can identify a credential stored in Windows Credential Manager or Apple Keychain instead of embedding the literal secret in application code.

      Secret specification format: !![appName|]service[|domain]|username.

      This feature applies to AddStringAt, AppendString, SetStringAt, SetStringOf, UpdateSb, and UpdateString.

      Security: Secret resolution changes where the string value comes from; the resulting JSON member still contains the resolved value. Avoid emitting or logging JSON that contains credentials unless that exposure is explicitly intended.

      Returns:
      the value of the EnableSecrets property

    • setEnableSecrets

      public void setEnableSecrets​(boolean value)
      Sets the EnableSecrets property; see getEnableSecrets().
      Parameters:
      value - the new value

    • getI

      public int getI()
      Supplies the integer substituted for i when a JSON path contains an array index such as [i]. This is useful for loop-based navigation without constructing a new path string for every iteration.

      Related properties: The J and K properties provide the same substitution behavior for [j] and [k].

      Returns:
      the value of the I property

    • setI

      public void setI​(int value)
      Sets the I property; see getI().
      Parameters:
      value - the new value

    • getJ

      public int getJ()
      Supplies the integer substituted for j when a JSON path contains [j]. It is commonly used with nested-array paths such as matrix[i][j].
      Returns:
      the value of the J property

    • setJ

      public void setJ​(int value)
      Sets the J property; see getJ().
      Parameters:
      value - the new value

    • getK

      public int getK()
      Supplies the integer substituted for k when a JSON path contains [k]. It can be combined with I and J for deeper nested-array traversal.
      Returns:
      the value of the K property

    • setK

      public void setK​(int value)
      Sets the K property; see getK().
      Parameters:
      value - the new value

    • getLowerCaseNames

      public boolean getLowerCaseNames()
      If true, member names are converted to lowercase while JSON is loaded by Load, LoadBd, LoadSb, or LoadFile. The default is false.

      Important: This changes member names in the parsed document; it is not merely a case-insensitive lookup mode. Use it only when normalizing names is intentional.

      Returns:
      the value of the LowerCaseNames property

    • setLowerCaseNames

      public void setLowerCaseNames​(boolean value)
      Sets the LowerCaseNames property; see getLowerCaseNames().
      Parameters:
      value - the new value

    • getPathPrefix

      public String getPathPrefix()
      Specifies a path prefix automatically prepended to JSON paths passed to path-based methods such as StringOf, ObjectOf, UpdateString, SetBoolOf, and SizeOfArray. The default is the empty string.

      Use case: Set a prefix when many operations target the same nested object. The individual method calls can then use paths relative to that prefix.

      Returns:
      the value of the PathPrefix property

    • setPathPrefix

      public void setPathPrefix​(String value)
      Sets the PathPrefix property; see getPathPrefix().
      Parameters:
      value - the new value (not null)

    • getSize

      public int getSize()
      Returns the number of direct name/value members in this JSON object. Nested members inside child objects are not included.

      JSON objects and order: RFC 8259 defines a JSON object as an unordered collection of name/value pairs. Chilkat preserves a member order so index-based APIs and deterministic emission are possible, but interoperable application logic should generally use member names rather than depend on object order.

      Returns:
      the value of the Size property (read-only)

    • getStrict

      public boolean getStrict()
      When Strict is true, the Load methods first check that the data is well-formed JSON. If it is not, the load fails and the contents of this JsonObject are left unchanged. The default is false.

      This applies to load(String), loadSb(StringBuilder), loadBd(BinData), loadFile(String) and loadPredefined(String).

      Chilkat's JSON parser is deliberately tolerant. By default it can accept text that is not well-formed, succeed, and leave an empty or partially populated document. That is convenient when the goal is a best-effort parse of imperfect input, but it is the wrong behavior when a silently missing member changes what the application does. A single missing comma, for example, can cause the members after it to be dropped while the load still reports success.

      Set Strict to true for JSON carrying configuration, credentials, or security parameters, where a member that quietly failed to load would be acted on as though it had never been specified.

      Note: The default is false so that existing applications are unaffected. When a strict load is rejected, this JsonObject keeps whatever it held before the call, so a failed reload never leaves the object empty.

      Returns:
      the value of the Strict property

    • setStrict

      public void setStrict​(boolean value)
      Sets the Strict property; see getStrict().
      Parameters:
      value - the new value

    • getUncommonOptions

      public String getUncommonOptions()
      Provides a catch-all string for uncommon, implementation-specific options. The default is the empty string and it should normally remain empty.

      Recommendation: Do not invent option keywords. Set this property only when a specific JsonObject option is documented by Chilkat or provided by Chilkat support.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • addArrayAt

      public void addArrayAt​(int index, String name)
      Inserts a new JSON array member named name at the zero-based member position index. The new array is empty.

      0 Insert as the first member.

      -1 Append as the last member.

      n Insert at zero-based position n.

      Member name vs. JSON path: name is a direct member name, not a JSON path. Use an Update* or Set*Of method when addressing a nested value by path.

      Parameters:
      index - the index argument
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addArrayCopyAt

      public void addArrayCopyAt​(int index, String name, JsonArray jarr)
      Inserts a new JSON array member named name at the zero-based member position index. The array value is copied from jarr; subsequent changes to the source array do not modify the inserted copy.

      0 Insert as the first member.

      -1 Append as the last member.

      n Insert at zero-based position n.

      Member name vs. JSON path: name is a direct member name, not a JSON path. Use an Update* or Set*Of method when addressing a nested value by path.

      Parameters:
      index - the index argument
      name - the name argument (not null)
      jarr - the jarr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addBoolAt

      public void addBoolAt​(int index, String name, boolean value)
      Inserts a new JSON boolean member named name at the zero-based member position index. The value is taken from value.

      0 Insert as the first member.

      -1 Append as the last member.

      n Insert at zero-based position n.

      Member name vs. JSON path: name is a direct member name, not a JSON path. Use an Update* or Set*Of method when addressing a nested value by path.

      Parameters:
      index - the index argument
      name - the name argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addIntAt

      public void addIntAt​(int index, String name, int value)
      Inserts a new JSON number member named name at the zero-based member position index. The integer value is emitted as a JSON number, not as a quoted string.

      0 Insert as the first member.

      -1 Append as the last member.

      n Insert at zero-based position n.

      Member name vs. JSON path: name is a direct member name, not a JSON path. Use an Update* or Set*Of method when addressing a nested value by path.

      Parameters:
      index - the index argument
      name - the name argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addNullAt

      public void addNullAt​(int index, String name)
      Inserts a new JSON null member named name at the zero-based member position index.

      0 Insert as the first member.

      -1 Append as the last member.

      n Insert at zero-based position n.

      Member name vs. JSON path: name is a direct member name, not a JSON path. Use an Update* or Set*Of method when addressing a nested value by path.

      Parameters:
      index - the index argument
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addNumberAt

      public void addNumberAt​(int index, String name, String numericStr)
      Inserts a new JSON number member named name at the zero-based member position index. The numericStr argument supplies the exact JSON numeric text to store.

      0 Insert as the first member.

      -1 Append as the last member.

      n Insert at zero-based position n.

      Member name vs. JSON path: name is a direct member name, not a JSON path. Use an Update* or Set*Of method when addressing a nested value by path.Exact numeric text: Use this method when lexical form or precision matters, for example 12345678901234567890, 1.2500, or scientific notation. The supplied text must be valid JSON number syntax; JSON does not permit NaN or infinity.

      Parameters:
      index - the index argument
      name - the name argument (not null)
      numericStr - the numericStr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addObjectAt

      public void addObjectAt​(int index, String name)
      Inserts a new JSON object member named name at the zero-based member position index. The new object is empty.

      0 Insert as the first member.

      -1 Append as the last member.

      n Insert at zero-based position n.

      Member name vs. JSON path: name is a direct member name, not a JSON path. Use an Update* or Set*Of method when addressing a nested value by path.

      Parameters:
      index - the index argument
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addObjectCopyAt

      public void addObjectCopyAt​(int index, String name, JsonObject jsonObj)
      Inserts a new JSON object member named name at the zero-based member position index. The object value is copied from jsonObj; the inserted value is independent of the source.

      0 Insert as the first member.

      -1 Append as the last member.

      n Insert at zero-based position n.

      Member name vs. JSON path: name is a direct member name, not a JSON path. Use an Update* or Set*Of method when addressing a nested value by path.

      Parameters:
      index - the index argument
      name - the name argument (not null)
      jsonObj - the jsonObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addStringAt

      public void addStringAt​(int index, String name, String value)
      Inserts a new JSON string member named name at the zero-based member position index. The value is stored as a JSON string and is escaped as needed when emitted.

      0 Insert as the first member.

      -1 Append as the last member.

      n Insert at zero-based position n.

      Member name vs. JSON path: name is a direct member name, not a JSON path. Use an Update* or Set*Of method when addressing a nested value by path.

      Parameters:
      index - the index argument
      name - the name argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendArray

      public JsonArray appendArray​(String name)
      Appends a new JSON array member named name to this object. The newly appended array is empty and the returned JsonArray references that array in this document, so changes made through it modify the same JSON tree.

      Member name vs. JSON path: name is a direct member name. It is not interpreted as a JSON path. Use the corresponding Update* method when a nested path should be addressed or created.

      Parameters:
      name - the name argument (not null)
      Returns:
      a new JsonArray owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendArray2

      public void appendArray2​(String name, JsonArray jarr)
      Appends a new JSON array member named name to this object. A new empty array is created and jarr is updated to reference it. The method returns true on success.

      Member name vs. JSON path: name is a direct member name. It is not interpreted as a JSON path. Use the corresponding Update* method when a nested path should be addressed or created.

      Parameters:
      name - the name argument (not null)
      jarr - the jarr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendArrayCopy

      public void appendArrayCopy​(String name, JsonArray jarr)
      Appends a new JSON array member named name to this object. The array is copied from jarr, so the appended array is independent of the source array.

      Member name vs. JSON path: name is a direct member name. It is not interpreted as a JSON path. Use the corresponding Update* method when a nested path should be addressed or created.

      Parameters:
      name - the name argument (not null)
      jarr - the jarr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendBool

      public void appendBool​(String name, boolean value)
      Appends a new JSON boolean member named name to this object. The value is taken from value.

      Member name vs. JSON path: name is a direct member name. It is not interpreted as a JSON path. Use the corresponding Update* method when a nested path should be addressed or created.

      Parameters:
      name - the name argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendInt

      public void appendInt​(String name, int value)
      Appends a new JSON number member named name to this object. The integer value is stored as a JSON number.

      Member name vs. JSON path: name is a direct member name. It is not interpreted as a JSON path. Use the corresponding Update* method when a nested path should be addressed or created.

      Parameters:
      name - the name argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendObject

      public JsonObject appendObject​(String name)
      Appends a new JSON object member named name to this object. The newly appended object is empty and the returned JsonObject references that object in this document.

      Member name vs. JSON path: name is a direct member name. It is not interpreted as a JSON path. Use the corresponding Update* method when a nested path should be addressed or created.

      Parameters:
      name - the name argument (not null)
      Returns:
      a new JsonObject owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendObject2

      public void appendObject2​(String name, JsonObject jsonObj)
      Appends a new JSON object member named name to this object. A new empty object is created and jsonObj is updated to reference it. The method returns true on success.

      Member name vs. JSON path: name is a direct member name. It is not interpreted as a JSON path. Use the corresponding Update* method when a nested path should be addressed or created.

      Parameters:
      name - the name argument (not null)
      jsonObj - the jsonObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendObjectCopy

      public void appendObjectCopy​(String name, JsonObject jsonObj)
      Appends a new JSON object member named name to this object. The object is copied from jsonObj, so the appended object is independent of the source object.

      Member name vs. JSON path: name is a direct member name. It is not interpreted as a JSON path. Use the corresponding Update* method when a nested path should be addressed or created.

      Parameters:
      name - the name argument (not null)
      jsonObj - the jsonObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendString

      public void appendString​(String name, String value)
      Appends a new JSON string member named name to this object. The value is JSON-escaped as needed when emitted.

      Member name vs. JSON path: name is a direct member name. It is not interpreted as a JSON path. Use the corresponding Update* method when a nested path should be addressed or created.

      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendStringArray

      public void appendStringArray​(String name, StringTable values)
      Appends a new JSON array member named name to this object. The array is populated with the strings contained in values.

      Member name vs. JSON path: name is a direct member name. It is not interpreted as a JSON path. Use the corresponding Update* method when a nested path should be addressed or created.

      Parameters:
      name - the name argument (not null)
      values - the values argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • arrayAt

      public JsonArray arrayAt​(int index)
      Returns the JSON array stored in the member at zero-based position index. The returned JsonArray references the existing array in the same document; it is not a detached copy.

      Type requirement: The member at index must be an array. Use TypeAt when the member type is not already known.

      Parameters:
      index - the index argument
      Returns:
      a new JsonArray owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • arrayAt2

      public void arrayAt2​(int index, JsonArray jarr)
      Updates jarr to reference the JSON array stored at zero-based member position index and returns true on success.
      Parameters:
      index - the index argument
      jarr - the jarr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • arrayOf

      public JsonArray arrayOf​(String jsonPath)
      Returns the JSON array at jsonPath. The returned JsonArray references the existing array in the same document, so modifications through it are reflected in the parent JSON.

      JSON paths: Paths are relative to this object and may include object-member separators and array indexes, for example orders[0].items.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      Returns:
      a new JsonArray owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • arrayOf2

      public void arrayOf2​(String jsonPath, JsonArray jarr)
      Updates jarr to reference the JSON array at jsonPath and returns true on success.
      Parameters:
      jsonPath - the jsonPath argument (not null)
      jarr - the jarr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • boolAt

      public boolean boolAt​(int index)
      Returns the boolean value of the member at zero-based position index.

      Indexing: Member indexes are based on the order maintained by this JsonObject instance. JSON objects are semantically unordered, so application protocols should normally identify values by member name rather than by position.

      Parameters:
      index - the index argument
      Returns:
      the result; this method never throws ChilkatException

    • boolOf

      public boolean boolOf​(String jsonPath)
      Returns the boolean value at jsonPath. The path is evaluated relative to this JsonObject, after applying PathPrefix if one is set.
      Parameters:
      jsonPath - the jsonPath argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • bytesOf

      public void bytesOf​(String jsonPath, String encoding, BinData bd)
      Reads the string value at jsonPath, decodes it using encoding (for example, base64 or hex), and appends the resulting bytes to bd.

      Binary-in-JSON convention: The JSON member itself is text. The encoding argument tells Chilkat how that text represents the original bytes.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      encoding - the encoding argument (not null)
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clear

      public void clear()
      Removes all members from this JSON object, leaving an empty object equivalent to {}.

    • copyRef

      public void copyRef​(JsonObject jsonObj)
      Updates jsonObj so that it references the same JSON object as the caller. No JSON data is copied.

      Shared state: After this call, modifications through either reference affect the same underlying JSON object.

      Parameters:
      jsonObj - the jsonObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • dateOf

      public void dateOf​(String jsonPath, DateTime dt)
      Parses the date/time value at jsonPath and loads the result into dt. Recognized forms include ISO 8601 timestamps (for example, 2009-11-04T19:55:41Z), RFC 822-style date/time strings, and Unix timestamp integers.

      JSON has no native date type: Dates in JSON are application conventions, usually represented as strings or numbers. This method recognizes common conventions and converts them to CkDateTime.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      dt - the dt argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • delete

      public void delete​(String name)
      Deletes the direct member named name from this JSON object.

      Not a path: name is a member name, not a JSON path. Use a path-based operation when deleting or replacing a nested value requires navigation first.

      Parameters:
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • deleteAt

      public void deleteAt​(int index)
      Deletes the member at zero-based position index. Members after the deleted position shift toward the beginning.
      Parameters:
      index - the index argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • deleteRecords

      public int deleteRecords​(String arrayPath, String relpath, String value, boolean caseSensitive)
      Deletes every object record in the array at arrayPath whose value at relative path relpath equals or wildcard-matches value. The caseSensitive argument controls matching. Returns the number of records deleted.
      Parameters:
      arrayPath - the arrayPath argument (not null)
      relpath - the relpath argument (not null)
      value - the value argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • dtOf

      public void dtOf​(String jsonPath, boolean bLocal, DtObj dt)
      Parses the date/time value at jsonPath into dt. If bLocal is true, the destination receives local date/time fields; otherwise it receives UTC/GMT fields. Recognized inputs include ISO 8601 timestamps, RFC 822-style date/time strings, and Unix timestamp integers.
      Parameters:
      jsonPath - the jsonPath argument (not null)
      bLocal - the bLocal argument
      dt - the dt argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • emit

      public String emit()
      Serializes the JSON document rooted at this object and returns the JSON text. Formatting is controlled by EmitCompact and, for pretty output, EmitCrLf.

      Object member order: Chilkat emits members in its maintained order, but JSON object ordering is not semantically significant under RFC 8259.

      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • emitBd

      public void emitBd​(BinData bd)
      Serializes this JSON and appends the resulting bytes to bd.

      Append behavior: Existing data in the destination BinData is preserved.

      Parameters:
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • emitSb

      public void emitSb​(StringBuilder sb)
      Serializes this JSON and appends the resulting text to sb. Formatting follows EmitCompact and EmitCrLf.

      Append behavior: Existing text in the destination StringBuilder is preserved; the emitted JSON is added after it.

      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • emitWithSubs

      public String emitWithSubs​(Hashtable subs, boolean omitEmpty)
      Serializes the JSON after substituting variables from subs into template strings. A placeholder such as {$name} is replaced by the corresponding hashtable value. Prefixing the variable name with i., as in {$i.count}, emits the substituted value as a JSON integer instead of a quoted string.

      If omitEmpty is true, members whose substituted result is an empty string or empty array are omitted from the emitted JSON.

      Template reuse: This method does not require rebuilding the JSON template. It is commonly paired with Predefine and LoadPredefined when the same JSON shape is emitted repeatedly with different values.

      Parameters:
      subs - the subs argument (not null)
      omitEmpty - the omitEmpty argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • findObjectWithMember

      public JsonObject findObjectWithMember​(String name)
      Recursively searches this JSON subtree for the first JSON object containing a direct member named name. Returns that object, or null if no matching object is found.
      Parameters:
      name - the name argument (not null)
      Returns:
      a new JsonObject owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • findObjectWithMember2

      public void findObjectWithMember2​(String name, JsonObject jsonObj)
      Recursively searches this JSON subtree for the first object containing a direct member named name. On success, jsonObj is updated to reference the matching object and the method returns true.
      Parameters:
      name - the name argument (not null)
      jsonObj - the jsonObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • findRecord

      public JsonObject findRecord​(String arrayPath, String relPath, String value, boolean caseSensitive)
      Searches the JSON array at arrayPath for the first object whose value at relative path relPath equals or wildcard-matches value. The caseSensitive argument controls string comparison. Returns the matching record object.

      Wildcard matching: The search value may contain * to match zero or more characters. relPath is evaluated relative to each record object in the array.

      Parameters:
      arrayPath - the arrayPath argument (not null)
      relPath - the relPath argument (not null)
      value - the value argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      a new JsonObject owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • findRecord2

      public void findRecord2​(String arrayPath, String relPath, String value, boolean caseSensitive, JsonObject jsonObj)
      Searches the JSON array at arrayPath using the same matching rules as FindRecord. On success, jsonObj is updated to reference the first matching record and the method returns true.

      Reference semantics: The destination references the record in the original JSON document; changes made through jsonObj modify that record.

      Parameters:
      arrayPath - the arrayPath argument (not null)
      relPath - the relPath argument (not null)
      value - the value argument (not null)
      caseSensitive - the caseSensitive argument
      jsonObj - the jsonObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • findRecordString

      public String findRecordString​(String arrayPath, String relPath, String value, boolean caseSensitive, String retRelPath)
      Searches the JSON array at arrayPath for the first record whose relPath value equals or wildcard-matches value, then returns the value at retRelPath from that same record as a string.

      Typical use: This is useful for lookups such as “find the record where Name is Advertising and return its Id.” The * wildcard may be used in value.

      Parameters:
      arrayPath - the arrayPath argument (not null)
      relPath - the relPath argument (not null)
      value - the value argument (not null)
      caseSensitive - the caseSensitive argument
      retRelPath - the retRelPath argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • firebaseApplyEvent

      public void firebaseApplyEvent​(String name, String data)
      Applies a Firebase Realtime Database event to this JSON object. name should be put or patch, and data should contain event JSON such as {"path":"/","data":{"a":1,"b":2}}.

      Purpose: This method is useful when maintaining a local JSON representation from Firebase server-sent events: put replaces the value at a path, while patch updates individual child keys.

      Parameters:
      name - the name argument (not null)
      data - the data argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • firebasePatch

      public void firebasePatch​(String jsonPath, String jsonData)
      Applies Firebase-style patch semantics at jsonPath. jsonData must contain a JSON object; each key in that object updates or adds the corresponding key at the target path.

      Relative path: jsonPath is relative to this JsonObject.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      jsonData - the jsonData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • firebasePut

      public void firebasePut​(String jsonPath, String value)
      Applies Firebase-style put semantics at jsonPath, replacing or inserting the value at that path. value is JSON text and may represent an object, array, number, boolean, null, or a quoted JSON string.

      Quoted strings: To store a string through this method, value must contain a valid JSON string literal, including its surrounding double quotes. Use UpdateString when you already have an ordinary application string.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getDocRoot

      public JsonObject getDocRoot()
      Returns a JsonObject reference to the root object of the JSON document containing this object. This can be called from any nested object reference.

      Shared document lifetime: Nested JsonObject references share the same underlying JSON document. The document remains available while at least one such reference is retained by the application.

      Returns:
      a new JsonObject owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getDocRoot2

      public void getDocRoot2​(JsonObject docRoot)
      Updates docRoot to reference the root object of the JSON document containing the caller and returns true on success.

      Reference semantics: The destination is another reference into the same underlying document; it is not a copy.

      Parameters:
      docRoot - the docRoot argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • hasMember

      public boolean hasMember​(String jsonPath)
      Returns true if a value exists at jsonPath; otherwise returns false.

      Missing vs. null: A member whose JSON value is null still exists. Use IsNullOf to test specifically for JSON null.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • indexOf

      public int indexOf​(String name)
      Returns the zero-based position of the direct member named name, or -1 if that member name is not found.

      Not a path: name is searched only among the direct members of this object.

      Parameters:
      name - the name argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • intAt

      public int intAt​(int index)
      Returns the integer value of the member at zero-based position index.

      Indexing: Member indexes are based on the order maintained by this JsonObject instance. JSON objects are semantically unordered, so application protocols should normally identify values by member name rather than by position.

      Parameters:
      index - the index argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • intOf

      public int intOf​(String jsonPath)
      Returns the integer value at jsonPath. The path is evaluated relative to this JsonObject, after applying PathPrefix if one is set.

      Large numbers: Use StringOf or the exact numeric-text APIs when a JSON integer may exceed the range of the language binding's integer type.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • isNullAt

      public boolean isNullAt​(int index)
      Returns true if the member at zero-based position index has the JSON value null; otherwise returns false.
      Parameters:
      index - the index argument
      Returns:
      the result; this method never throws ChilkatException

    • isNullOf

      public boolean isNullOf​(String jsonPath)
      Returns true if the value at jsonPath is the JSON literal null; otherwise returns false.

      Null is a value: JSON null is different from a missing member and from an empty string. Use HasMember when existence must be tested separately.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • jsonTypeOf

      public int jsonTypeOf​(String jsonPath)
      Returns an integer identifying the JSON type of the value at jsonPath. Returns -1 if no member exists at that path.

      1 string

      2 number

      3 object

      4 array

      5 boolean

      6 null

      Parameters:
      jsonPath - the jsonPath argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • load

      public void load​(String json)
      Parses the JSON text in json and loads the parsed data into this object for DOM-style access and modification.

      JSON data model: JSON values are strings, numbers, booleans, null, objects, or arrays. Object member names should be unique for interoperable JSON; RFC 8259 notes that consumers differ in how duplicate names are handled.

      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadBd

      public void loadBd​(BinData bd)
      Parses JSON from the bytes contained in bd and loads it into this object.
      Parameters:
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadFile

      public void loadFile​(String path)
      Reads JSON text from the file at path, parses it, and loads the result into this object.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPredefined

      public void loadPredefined​(String name)
      Loads this object from the predefined JSON document identified by name. Predefined documents are created with Predefine.
      Parameters:
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadSb

      public void loadSb​(StringBuilder sb)
      Parses JSON from the current contents of sb and loads it into this object.
      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • makeCopy

      public void makeCopy​(JsonObject json)
      Copies this JSON object into json. The destination receives an independent JSON copy rather than another reference to the same underlying object.

      Copy vs. reference: Use CopyRef when two JsonObject instances should refer to the same JSON object instead of duplicating its data.

      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • moveMember

      public void moveMember​(int fromIndex, int toIndex)
      Moves the direct member at zero-based position fromIndex to toIndex. Use toIndex = 0 to move it first or -1 to move it last.
      Parameters:
      fromIndex - the fromIndex argument
      toIndex - the toIndex argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • nameAt

      public String nameAt​(int index)
      Returns the name of the member at zero-based position index. Use this with Size and TypeAt to iterate through an object's direct members.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • newArrayOf

      public void newArrayOf​(String path, String jArr)
      Creates a JSON array at path and loads that array from the JSON text in jArr. The supplied text should represent a JSON array.

      Difference from UpdateNewArray: UpdateNewArray creates an empty array. NewArrayOf creates the array and immediately populates it from JSON text.

      Parameters:
      path - the path argument (not null)
      jArr - the jArr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • newObjectOf

      public void newObjectOf​(String path, String jObj)
      Creates a JSON object at path and loads that object from the JSON text in jObj. The supplied text should represent a JSON object.

      Difference from UpdateNewObject: UpdateNewObject creates an empty object. NewObjectOf creates the object and immediately populates it from JSON text.

      Parameters:
      path - the path argument (not null)
      jObj - the jObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • objectAt

      public JsonObject objectAt​(int index)
      Returns the JSON object stored in the member at zero-based position index. The returned JsonObject references the existing child object in the same document; changes made through it modify that document.

      Type requirement: The member at index must be a JSON object. Use TypeAt when the type is not already known.

      Parameters:
      index - the index argument
      Returns:
      a new JsonObject owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • objectAt2

      public void objectAt2​(int index, JsonObject jsonObj)
      Updates jsonObj to reference the JSON object stored at zero-based member position index and returns true on success.
      Parameters:
      index - the index argument
      jsonObj - the jsonObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • objectOf

      public JsonObject objectOf​(String jsonPath)
      Returns the JSON object at jsonPath. The returned object is a live reference into the same JSON document, not a copy.

      Relative paths: A path is evaluated relative to the current object. Use GetDocRoot when access must start from the document root.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      Returns:
      a new JsonObject owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • objectOf2

      public void objectOf2​(String jsonPath, JsonObject jsonObj)
      Updates jsonObj to reference the JSON object at jsonPath and returns true on success.
      Parameters:
      jsonPath - the jsonPath argument (not null)
      jsonObj - the jsonObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • predefine

      public void predefine​(String name)
      Stores this JSON document in Chilkat's internal global collection of predefined JSON documents under name. If the name already exists, the predefined value is replaced.

      Template use: After predefining a document, another JsonObject can load it by name with LoadPredefined.

      Parameters:
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • rename

      public void rename​(String oldName, String newName)
      Renames the direct member oldName to newName. The member value and its position are otherwise unchanged.

      JSON interoperability: JSON object member names should be unique. Avoid renaming a member to a name already used by another member unless duplicate names are intentionally required.

      Parameters:
      oldName - the oldName argument (not null)
      newName - the newName argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • renameAt

      public void renameAt​(int index, String name)
      Renames the member at zero-based position index to name. The member value is not changed.
      Parameters:
      index - the index argument
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setBoolAt

      public void setBoolAt​(int index, boolean value)
      Sets the member at zero-based position index to a JSON boolean value.
      Parameters:
      index - the index argument
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setBoolOf

      public void setBoolOf​(String jsonPath, boolean value)
      Sets the value at jsonPath to a JSON boolean value.

      Set vs. Update: Use UpdateBool when missing objects or array positions along the path should be created automatically.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setIntAt

      public void setIntAt​(int index, int value)
      Sets the member at zero-based position index to a JSON number value. The integer is emitted as a JSON number.
      Parameters:
      index - the index argument
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setIntOf

      public void setIntOf​(String jsonPath, int value)
      Sets the value at jsonPath to an integer JSON number.

      Set vs. Update: Use UpdateInt when missing objects or array positions along the path should be created automatically.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setNullAt

      public void setNullAt​(int index)
      Sets the member at zero-based position index to a JSON null value.
      Parameters:
      index - the index argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setNullOf

      public void setNullOf​(String jsonPath)
      Sets the value at jsonPath to a JSON null value.

      Set vs. Update: Use UpdateNull when missing objects or array positions along the path should be created automatically.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setNumberAt

      public void setNumberAt​(int index, String value)
      Sets the member at zero-based position index to a JSON number value. The value argument is the exact textual representation of the JSON number.

      JSON number syntax: The text may contain an integer, fraction, or exponent. It must be valid JSON number syntax; leading zeros (except for zero itself), NaN, and infinity are not valid JSON numbers.

      Parameters:
      index - the index argument
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setNumberOf

      public void setNumberOf​(String jsonPath, String value)
      Sets the value at jsonPath to a JSON number value. The value argument supplies the exact textual form of the JSON number.

      Set vs. Update: Use UpdateNumber when missing objects or array positions along the path should be created automatically.Precision: Using numeric text avoids an intermediate conversion through a floating-point type and can therefore preserve large integers or application-specific decimal formatting.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setStringAt

      public void setStringAt​(int index, String value)
      Sets the member at zero-based position index to a JSON string value. The string is escaped as required when JSON is emitted.
      Parameters:
      index - the index argument
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setStringOf

      public void setStringOf​(String jsonPath, String value)
      Sets the value at jsonPath to a JSON string value. The string is escaped as required when JSON is emitted.

      Set vs. Update: Use UpdateString when missing objects or array positions along the path should be created automatically.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sizeOfArray

      public int sizeOfArray​(String jsonPath)
      Returns the number of elements in the JSON array at jsonPath. Returns -1 if the path does not resolve to an existing JSON array.
      Parameters:
      jsonPath - the jsonPath argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • sort

      public void sort​(boolean ascending, boolean caseSensitive)
      Sorts this object's direct members by member name. ascending selects ascending or descending order, and caseSensitive controls how names are compared.

      JSON semantics: Member ordering is not significant to JSON consumers, but sorting can make emitted JSON deterministic and easier to compare or review.

      Parameters:
      ascending - the ascending argument
      caseSensitive - the caseSensitive argument

    • stringAt

      public String stringAt​(int index)
      Returns the string value of the member at zero-based position index.

      Indexing: Member indexes are based on the order maintained by this JsonObject instance. JSON objects are semantically unordered, so application protocols should normally identify values by member name rather than by position.Non-string values: StringOf can also provide textual representations of scalar JSON values such as numbers, booleans, and null; use the type-specific methods when the JSON type itself matters.

      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • stringOf

      public String stringOf​(String jsonPath)
      Returns the value at jsonPath as text. For a JSON string, the string value is returned. Scalar non-string values such as numbers, booleans, and null are returned using their JSON textual representation.

      Type-sensitive code: Use JsonTypeOf, IntOf, BoolOf, or IsNullOf when the distinction between JSON types is important.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • stringOfEquals

      public boolean stringOfEquals​(String jsonPath, String value, boolean caseSensitive)
      Returns true if the textual value at jsonPath equals value according to the caseSensitive setting; otherwise returns false.
      Parameters:
      jsonPath - the jsonPath argument (not null)
      value - the value argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result; this method never throws ChilkatException

    • stringOfSb

      public void stringOfSb​(String jsonPath, StringBuilder sb)
      Retrieves the value at jsonPath as text and appends it to sb.

      Append behavior: Existing contents of the destination StringBuilder are preserved.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • swap

      public void swap​(int index1, int index2)
      Swaps the positions of the direct members at zero-based indexes index1 and index2. Member names and values are unchanged.

      Ordering: JSON object order is not semantically significant, but Chilkat preserves an order for index-based access and emission.

      Parameters:
      index1 - the index1 argument
      index2 - the index2 argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • typeAt

      public int typeAt​(int index)
      Returns an integer identifying the JSON type of the member at zero-based position index. Returns -1 if no member exists at that index.

      1 string

      2 number

      3 object

      4 array

      5 boolean

      6 null

      Parameters:
      index - the index argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • uIntOf

      public long uIntOf​(String jsonPath)
      Returns the unsigned integer value at jsonPath.
      Parameters:
      jsonPath - the jsonPath argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • updateBd

      public void updateBd​(String jsonPath, String encoding, BinData bd)
      Updates the value at jsonPath to a JSON string value, or creates the member and any missing path components as needed. The bytes in bd are first encoded according to encoding (for example, base64 or hex) and the encoded text is stored as the JSON string value.

      Path-based operation: jsonPath is interpreted using DelimiterChar, PathPrefix, and the I/J/K index substitutions.Binary data in JSON: JSON has no native byte-array type. Binary content must therefore be represented using a textual encoding agreed upon by the producer and consumer.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      encoding - the encoding argument (not null)
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateBool

      public void updateBool​(String jsonPath, boolean value)
      Updates the value at jsonPath to a JSON boolean value, or creates the member and any missing path components as needed.

      Path-based operation: jsonPath is interpreted using DelimiterChar, PathPrefix, and the I/J/K index substitutions.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateInt

      public void updateInt​(String jsonPath, int value)
      Updates the value at jsonPath to a JSON number value, or creates the member and any missing path components as needed. The integer value is stored as a JSON number.

      Path-based operation: jsonPath is interpreted using DelimiterChar, PathPrefix, and the I/J/K index substitutions.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateNewArray

      public void updateNewArray​(String jsonPath)
      Creates or replaces the value at jsonPath with a new empty JSON array. Missing path components are created automatically as needed.
      Parameters:
      jsonPath - the jsonPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateNewObject

      public void updateNewObject​(String jsonPath)
      Creates or replaces the value at jsonPath with a new empty JSON object. Missing path components are created automatically as needed.
      Parameters:
      jsonPath - the jsonPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateNull

      public void updateNull​(String jsonPath)
      Updates the value at jsonPath to a JSON null value, or creates the member and any missing path components as needed.

      Path-based operation: jsonPath is interpreted using DelimiterChar, PathPrefix, and the I/J/K index substitutions.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateNumber

      public void updateNumber​(String jsonPath, String numericStr)
      Updates the value at jsonPath to a JSON number value, or creates the member and any missing path components as needed. The numericStr argument is stored as the exact textual representation of the JSON number.

      Path-based operation: jsonPath is interpreted using DelimiterChar, PathPrefix, and the I/J/K index substitutions.When to use: Use UpdateNumber instead of UpdateInt for decimal/exponent forms, very large integers, or when preserving exact numeric text is important.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      numericStr - the numericStr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateSb

      public void updateSb​(String jsonPath, StringBuilder sb)
      Updates the value at jsonPath to a JSON string value, or creates the member and any missing path components as needed. The new string value is taken from the contents of sb.

      Path-based operation: jsonPath is interpreted using DelimiterChar, PathPrefix, and the I/J/K index substitutions.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateString

      public void updateString​(String jsonPath, String value)
      Updates the value at jsonPath to a JSON string value, or creates the member and any missing path components as needed. The supplied string is JSON-escaped as needed.

      Path-based operation: jsonPath is interpreted using DelimiterChar, PathPrefix, and the I/J/K index substitutions.Version note: Chilkat versions prior to 9.5.0.68 did not correctly escape all characters for this method. Version 9.5.0.68 and later correct that behavior.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateUInt

      public void updateUInt​(String jsonPath, long value)
      Updates the value at jsonPath to a JSON number value, or creates the member and any missing path components as needed. The unsigned integer is stored as a JSON number.

      Path-based operation: jsonPath is interpreted using DelimiterChar, PathPrefix, and the I/J/K index substitutions.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      value - the value argument (0 .. 4294967295)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • writeFile

      public void writeFile​(String path)
      Serializes this JSON and writes it to the file at path. Output formatting follows EmitCompact and EmitCrLf.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why