Package org.forgerock.json.resource

Class PatchOperation

java.lang.Object
org.forgerock.json.resource.PatchOperation
public final class PatchOperation extends Object
An individual patch operation which is to be performed against a field within a resource. This class defines four core types of operation. The core operations are defined below and their behavior depends on the type of the field being targeted by the operation:
  • an object (Java Map) or primitive (Java String, Boolean, or Number): these are considered to be single-valued fields
  • an array (Java List): these are considered to be multi-valued fields exhibiting either:
    • list semantics - an ordered collection of potentially non-unique values, or
    • set semantics - a collection of unique values whose ordering is implementation defined.
    The choice of semantic (list or set) associated with a multi-valued field is implementation defined, although it is usual for it to be defined using a schema.
The four core patch operations are:
  • add - ensures that the targeted field contains the provided value(s). Missing parent fields will be created as needed. If the targeted field is already present and it is single-valued (i.e. not an array) then the existing value will be replaced. If the targeted field is already present and it is multi-valued (i.e. an array) then the behavior depends on whether the field is a list or a set:
    • list - the provided array of values will be appended to the existing list of values,
    • set - the provided array of values will be merged with the existing set of values and duplicates removed.
    Add operations which target a specific index of a multi-valued field are permitted as long as the field is a list. In this case the patch value must represent a single element of the list (i.e. it must not be an array of new elements) which will be inserted at the specified position. Indexed updates to sets are not permitted, although implementations may support the special index "-" which can be used to add a single value to a list or set.
  • remove - ensures that the targeted field does not contain the provided value(s) if present. If no values are provided with the remove operation then the entire field will be removed if it is present. If the remove operation targets a single-valued field and a patch value is provided then it must match the existing value for it to be removed, otherwise the field is left unchanged. If the remove operation targets a multi-valued field then the behavior depends on whether the field is a list or a set:
    • list - the provided array of values will be removed from the existing list of values. Each value in the remove operation will result in at most one value being removed from the existing list. In other words, if the existing list contains a pair of duplicate values and both of them need to be removed, then the values must be include twice in the remove operation,
    • set - the provided array of values will be removed from the existing set of values.
    Remove operations which target a specific index of a multi-valued field are permitted as long as the field is a list. If a patch value is provided then it must match the existing value for it to be removed, otherwise the field is left unchanged. Indexed updates to sets are not permitted.
  • replace - removes any existing value(s) of the targeted field and replaces them with the provided value(s). A replace operation is semantically equivalent to a remove followed by an add, except that indexed updates are not permitted regardless of whether or not the field is a list.
  • increment - increments or decrements the targeted numerical field value(s) by the specified amount. If the amount is negative then the value(s) are decremented. It is an error to attempt to increment a field which does not contain a number or an array of numbers. It is also an error if the patch value is not a single value.

NOTE: this class does not define how field values will be matched, nor does it define whether a resource supports indexed based modifications, nor whether fields are single or multi-valued. Instead these matters are the responsibility of the resource provider and, in particular, the JSON schema being enforced for the targeted resource.

  • Field Details

    • FIELD_FIELD

      public static final String FIELD_FIELD
      The name of the field which contains the target field in the JSON representation.
      See Also:

    • FIELD_FROM

      public static final String FIELD_FROM
      The name of the source field for copy and move operations.
      See Also:

    • FIELD_OPERATION

      public static final String FIELD_OPERATION
      The name of the field which contains the type of patch operation in the JSON representation.
      See Also:

    • FIELD_VALUE

      public static final String FIELD_VALUE
      The name of the field which contains the operation value in the JSON representation.
      See Also:

    • OPERATION_ADD

      public static final String OPERATION_ADD
      The identifier used for "add" operations.
      See Also:

    • OPERATION_INCREMENT

      public static final String OPERATION_INCREMENT
      The identifier used for "increment" operations.
      See Also:

    • OPERATION_REMOVE

      public static final String OPERATION_REMOVE
      The identifier used for "remove" operations.
      See Also:

    • OPERATION_REPLACE

      public static final String OPERATION_REPLACE
      The identifier used for "replace" operations.
      See Also:

    • OPERATION_MOVE

      public static final String OPERATION_MOVE
      The identifier used for "move" operations.
      See Also:

    • OPERATION_COPY

      public static final String OPERATION_COPY
      The identifier used for "copy" operations.
      See Also:

    • OPERATION_TRANSFORM

      public static final String OPERATION_TRANSFORM
      The identifier used for "transform" operations. This is similar to an "add" or "replace" but the value may be treated as something other than a raw object.
      See Also:

  • Method Details

    • add

      public static PatchOperation add(JsonPointer field, Object value)
      Creates a new "add" patch operation which will add the provided value(s) to the specified field.
      Parameters:
      field - The field to be added.
      value - The new value(s) to be added, which may be a JsonValue or a JSON object, such as a String, Map, etc.
      Returns:
      The new patch operation.
      Throws:
      NullPointerException - If the value is null.

    • add

      public static PatchOperation add(String field, Object value)
      Creates a new "add" patch operation which will add the provided value(s) to the specified field.
      Parameters:
      field - The field to be added.
      value - The new value(s) to be added, which may be a JsonValue or a JSON object, such as a String, Map, etc.
      Returns:
      The new patch operation.
      Throws:
      NullPointerException - If the value is null.

    • increment

      public static PatchOperation increment(JsonPointer field, Number amount)
      Creates a new "increment" patch operation which will increment the value(s) of the specified field by the amount provided.
      Parameters:
      field - The field to be incremented.
      amount - The amount to be added or removed (if negative) from the field's value(s).
      Returns:
      The new patch operation.
      Throws:
      NullPointerException - If the amount is null.

    • increment

      public static PatchOperation increment(String field, Number amount)
      Creates a new "increment" patch operation which will increment the value(s) of the specified field by the amount provided.
      Parameters:
      field - The field to be incremented.
      amount - The amount to be added or removed (if negative) from the field's value(s).
      Returns:
      The new patch operation.
      Throws:
      NullPointerException - If the amount is null.

    • remove

      public static PatchOperation remove(JsonPointer field)
      Creates a new "remove" patch operation which will remove the specified field.
      Parameters:
      field - The field to be removed.
      Returns:
      The new patch operation.

    • remove

      public static PatchOperation remove(JsonPointer field, Object value)
      Creates a new "remove" patch operation which will remove the provided value(s) from the specified field.
      Parameters:
      field - The field to be removed.
      value - The value(s) to be removed, which may be a JsonValue or a JSON object, such as a String, Map, etc.
      Returns:
      The new patch operation.

    • remove

      public static PatchOperation remove(String field)
      Creates a new "remove" patch operation which will remove the specified field.
      Parameters:
      field - The field to be removed.
      Returns:
      The new patch operation.

    • remove

      public static PatchOperation remove(String field, Object value)
      Creates a new "remove" patch operation which will remove the provided value(s) from the specified field.
      Parameters:
      field - The field to be removed.
      value - The value(s) to be removed, which may be a JsonValue or a JSON object, such as a String, Map, etc.
      Returns:
      The new patch operation.

    • replace

      public static PatchOperation replace(JsonPointer field, Object value)
      Creates a new "replace" patch operation which will replace the value(s) of the specified field with the provided value(s).
      Parameters:
      field - The field to be replaced.
      value - The new value(s) for the field, which may be a JsonValue or a JSON object, such as a String, Map, etc.
      Returns:
      The new patch operation.

    • replace

      public static PatchOperation replace(String field, Object value)
      Creates a new "replace" patch operation which will replace the value(s) of the specified field with the provided value(s).
      Parameters:
      field - The field to be replaced.
      value - The new value(s) for the field, which may be a JsonValue or a JSON object, such as a String, Map, etc.
      Returns:
      The new patch operation.

    • move

      public static PatchOperation move(JsonPointer from, JsonPointer field)
      Creates a new "move" patch operation which will move the value found at `from` to `path`.
      Parameters:
      from - The field to be moved.
      field - The destination path for the moved value
      Returns:
      The new patch operation.
      Throws:
      NullPointerException - If the from or path is null.

    • move

      public static PatchOperation move(String from, String field)
      Creates a new "move" patch operation which will move the value found at `from` to `path`.
      Parameters:
      from - The field to be moved.
      field - The destination path for the moved value
      Returns:
      The new patch operation.
      Throws:
      NullPointerException - If the from or path is null.

    • copy

      public static PatchOperation copy(JsonPointer from, JsonPointer field)
      Creates a new "copy" patch operation which will copy the value found at `from` to `path`.
      Parameters:
      from - The field to be copied.
      field - The destination path for the copied value
      Returns:
      The new patch operation.
      Throws:
      NullPointerException - If the from or path is null.

    • copy

      public static PatchOperation copy(String from, String field)
      Creates a new "copy" patch operation which will copy the value found at `from` to `path`.
      Parameters:
      from - The field to be copied.
      field - The destination path for the copied value
      Returns:
      The new patch operation.
      Throws:
      NullPointerException - If the from or path is null.

    • transform

      public static PatchOperation transform(JsonPointer field, Object transform)
      Creates a new "transform" patch operation which sets the value at field based on a transformation.
      Parameters:
      field - The field to be set.
      transform - The transform to be used to set the field value.
      Returns:
      The new patch operation.
      Throws:
      NullPointerException - If the transform is null.

    • transform

      public static PatchOperation transform(String field, Object transform)
      Creates a new "transform" patch operation which sets the value at field based on a transformation.
      Parameters:
      field - The field to be set.
      transform - The transform to be used to set the field value.
      Returns:
      The new patch operation.
      Throws:
      NullPointerException - If the transform is null.

    • operation

      public static PatchOperation operation(String operation, JsonPointer field, Object value)
      Creates a new patch operation having the specified operation type, field, and value(s).
      Parameters:
      operation - The type of patch operation to be performed.
      field - The field targeted by the patch operation.
      value - The possibly null value for the patch operation, which may be a JsonValue or a JSON object, such as a String, Map, etc.
      Returns:
      The new patch operation.

    • operation

      public static PatchOperation operation(String operation, String field, Object value)
      Creates a new patch operation having the specified operation type, field, and value(s).
      Parameters:
      operation - The type of patch operation to be performed.
      field - The field targeted by the patch operation.
      value - The possibly null value for the patch operation, which may be a JsonValue or a JSON object, such as a String, Map, etc.
      Returns:
      The new patch operation.

    • copyOf

      public static PatchOperation copyOf(PatchOperation operation)
      Returns a deep copy of the provided patch operation. This method may be used in cases where the immutability of the underlying JSON value cannot be guaranteed.
      Parameters:
      operation - The patch operation to be defensively copied.
      Returns:
      A deep copy of the provided patch operation.

    • valueOf

      public static PatchOperation valueOf(JsonValue json) throws BadRequestException
      Parses the provided JSON content as a patch operation.
      Parameters:
      json - The patch operation to be parsed.
      Returns:
      The parsed patch operation.
      Throws:
      BadRequestException - If the JSON value is not a JSON patch operation.

    • valueOfList

      public static List<PatchOperation> valueOfList(JsonValue json) throws BadRequestException
      Parses the provided JSON content as a list of patch operations.
      Parameters:
      json - The list of patch operations to be parsed.
      Returns:
      The list of parsed patch operations.
      Throws:
      BadRequestException - If the JSON value is not a list of JSON patch operations.

    • getField

      public JsonPointer getField()
      Returns the field targeted by the patch operation.
      Returns:
      The field targeted by the patch operation.

    • getFrom

      public JsonPointer getFrom()
      Returns the source field for move and copy operations.
      Returns:
      The source field for move and copy operations.

    • getOperation

      public String getOperation()
      Returns the type of patch operation to be performed.
      Returns:
      The type of patch operation to be performed.

    • getValue

      public JsonValue getValue()
      Returns the value for the patch operation. The return value may be a JSON value whose value is null.
      Returns:
      The nullable value for the patch operation.

    • isAdd

      public boolean isAdd()
      Returns true if this is an "add" patch operation.
      Returns:
      true if this is an "add" patch operation.

    • isIncrement

      public boolean isIncrement()
      Returns true if this is an "increment" patch operation.
      Returns:
      true if this is an "increment" patch operation.

    • isRemove

      public boolean isRemove()
      Returns true if this is an "remove" patch operation.
      Returns:
      true if this is an "remove" patch operation.

    • isReplace

      public boolean isReplace()
      Returns true if this is an "replace" patch operation.
      Returns:
      true if this is an "replace" patch operation.

    • isMove

      public boolean isMove()
      Returns true if this is a "move" patch operation.
      Returns:
      true if this is a "move" patch operation.

    • isCopy

      public boolean isCopy()
      Returns true if this is a "copy" patch operation.
      Returns:
      true if this is a "copy" patch operation.

    • isTransform

      public boolean isTransform()
      Returns true if this is a "transform" patch operation.
      Returns:
      true if this is a "transform" patch operation.

    • toJsonValue

      public JsonValue toJsonValue()
      Returns a JSON value representation of this patch operation.
      Returns:
      A JSON value representation of this patch operation.

    • toString

      public String toString()
      Overrides:
      toString in class Object