Interface JsonEditor<N>

Type Parameters:
N - the node type of the caller's JSON representation
All Known Implementing Classes:
JacksonJsonModel
public interface JsonEditor<N>

Changes the caller's JSON values in place.

A JsonModel reads values and a JsonFactory builds new values. A model that also implements JsonEditor can change its objects and arrays without a copy. JSON Patch (RFC 6902) applies its operations through this interface. A model for immutable values, for example kotlinx.serialization, or for read-only values, for example a memory-mapped file, does not implement it.

Contract

  • No exceptions. For calls that obey the preconditions below, no method throws an exception.
  • Preconditions. The caller gives an object to the member methods and an array to the element methods, and an index in the stated range. The values that the caller inserts are nodes of the same model that are not already in the document (for example, from JsonFactory.copyOf(JsonModel, Object), or a node that the caller removed).
  • Results. Each method returns the value that it replaced or removed, so that the caller can reverse the change. After a change, the read methods of the model give the new values.
  • Unique names. An object has at most one member with a name. putMember(N, JsonString, N) replaces the value of an existing member.

The order of the members of an object is not significant (RFC 8259, Section 4). A model can add a new member at any position.

  • Method Details

    • putMember

      Maybe<N> putMember(N object, JsonString name, N value)
      Sets the value of a member. If the object has a member with the name, the method replaces its value. Otherwise, it adds a member.
      Parameters:
      object - a node of kind JsonKind.OBJECT
      name - the member name
      value - the new value
      Returns:
      the previous value, or Maybe.None if the object had no member with the name

    • removeMember

      Maybe<N> removeMember(N object, JsonString name)
      Removes a member.
      Parameters:
      object - a node of kind JsonKind.OBJECT
      name - the member name
      Returns:
      the removed value, or Maybe.None if the object had no member with the name

    • insertElement

      void insertElement(N array, int index, N value)
      Inserts an element. The elements at and after the index move one position to the right.
      Parameters:
      array - a node of kind JsonKind.ARRAY
      index - the index of the new element: from 0 to the length of the array. The length appends the element.
      value - the new element

    • setElement

      N setElement(N array, int index, N value)
      Replaces an element.
      Parameters:
      array - a node of kind JsonKind.ARRAY
      index - the index of the element: from 0 to the length of the array minus 1
      value - the new element
      Returns:
      the previous element

    • removeElement

      N removeElement(N array, int index)
      Removes an element. The elements after the index move one position to the left.
      Parameters:
      array - a node of kind JsonKind.ARRAY
      index - the index of the element: from 0 to the length of the array minus 1
      Returns:
      the removed element