PatchOperation (OpenAM Server Only 6.5.5 Documentation)

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 Summary

Fields
Modifier and Type	Field and Description
`static String`	`FIELD_FIELD` The name of the field which contains the target field in the JSON representation.
`static String`	`FIELD_FROM` The name of the source field for copy and move operations.
`static String`	`FIELD_OPERATION` The name of the field which contains the type of patch operation in the JSON representation.
`static String`	`FIELD_VALUE` The name of the field which contains the operation value in the JSON representation.
`static String`	`OPERATION_ADD` The identifier used for "add" operations.
`static String`	`OPERATION_COPY` The identifier used for "copy" operations.
`static String`	`OPERATION_INCREMENT` The identifier used for "increment" operations.
`static String`	`OPERATION_MOVE` The identifier used for "move" operations.
`static String`	`OPERATION_REMOVE` The identifier used for "remove" operations.
`static String`	`OPERATION_REPLACE` The identifier used for "replace" operations.
`static String`	`OPERATION_TRANSFORM` The identifier used for "transform" operations.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static PatchOperation`	`add(JsonPointer field, Object value)` Creates a new "add" patch operation which will add the provided value(s) to the specified field.
`static PatchOperation`	`add(String field, Object value)` Creates a new "add" patch operation which will add the provided value(s) to the specified field.
`static PatchOperation`	`copy(JsonPointer from, JsonPointer field)` Creates a new "copy" patch operation which will copy the value found at `from` to `path`.
`static PatchOperation`	`copy(String from, String field)` Creates a new "copy" patch operation which will copy the value found at `from` to `path`.
`static PatchOperation`	`copyOf(PatchOperation operation)` Returns a deep copy of the provided patch operation.
`JsonPointer`	`getField()` Returns the field targeted by the patch operation.
`JsonPointer`	`getFrom()` Returns the source field for move and copy operations.
`String`	`getOperation()` Returns the type of patch operation to be performed.
`JsonValue`	`getValue()` Returns the value for the patch operation.
`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.
`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.
`boolean`	`isAdd()` Returns `true` if this is an "add" patch operation.
`boolean`	`isCopy()` Returns `true` if this is a "copy" patch operation.
`boolean`	`isIncrement()` Returns `true` if this is an "increment" patch operation.
`boolean`	`isMove()` Returns `true` if this is a "move" patch operation.
`boolean`	`isRemove()` Returns `true` if this is an "remove" patch operation.
`boolean`	`isReplace()` Returns `true` if this is an "replace" patch operation.
`boolean`	`isTransform()` Returns `true` if this is a "transform" patch operation.
`static PatchOperation`	`move(JsonPointer from, JsonPointer field)` Creates a new "move" patch operation which will move the value found at `from` to `path`.
`static PatchOperation`	`move(String from, String field)` Creates a new "move" patch operation which will move the value found at `from` to `path`.
`static PatchOperation`	`operation(String operation, JsonPointer field, Object value)` Creates a new patch operation having the specified operation type, field, and value(s).
`static PatchOperation`	`operation(String operation, String field, Object value)` Creates a new patch operation having the specified operation type, field, and value(s).
`static PatchOperation`	`remove(JsonPointer field)` Creates a new "remove" patch operation which will remove the specified field.
`static PatchOperation`	`remove(JsonPointer field, Object value)` Creates a new "remove" patch operation which will remove the provided value(s) from the specified field.
`static PatchOperation`	`remove(String field)` Creates a new "remove" patch operation which will remove the specified field.
`static PatchOperation`	`remove(String field, Object value)` Creates a new "remove" patch operation which will remove the provided value(s) from the specified field.
`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).
`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).
`JsonValue`	`toJsonValue()` Returns a JSON value representation of this patch operation.
`String`	`toString()`
`static PatchOperation`	`transform(JsonPointer field, Object transform)` Creates a new "transform" patch operation which sets the value at field based on a transformation.
`static PatchOperation`	`transform(String field, Object transform)` Creates a new "transform" patch operation which sets the value at field based on a transformation.
`static PatchOperation`	`valueOf(JsonValue json)` Parses the provided JSON content as a patch operation.
`static List<PatchOperation>`	`valueOfList(JsonValue json)` Parses the provided JSON content as a list of patch operations.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - FIELD_FIELD
```
public static final String FIELD_FIELD
```
    The name of the field which contains the target field in the JSON representation.
    
    See Also:
    
    Constant Field Values
  - FIELD_FROM
```
public static final String FIELD_FROM
```
    The name of the source field for copy and move operations.
    
    See Also:
    
    Constant Field Values
  - 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:
    
    Constant Field Values
  - FIELD_VALUE
```
public static final String FIELD_VALUE
```
    The name of the field which contains the operation value in the JSON representation.
    
    See Also:
    
    Constant Field Values
  - OPERATION_ADD
```
public static final String OPERATION_ADD
```
    The identifier used for "add" operations.
    
    See Also:
    
    Constant Field Values
  - OPERATION_INCREMENT
```
public static final String OPERATION_INCREMENT
```
    The identifier used for "increment" operations.
    
    See Also:
    
    Constant Field Values
  - OPERATION_REMOVE
```
public static final String OPERATION_REMOVE
```
    The identifier used for "remove" operations.
    
    See Also:
    
    Constant Field Values
  - OPERATION_REPLACE
```
public static final String OPERATION_REPLACE
```
    The identifier used for "replace" operations.
    
    See Also:
    
    Constant Field Values
  - OPERATION_MOVE
```
public static final String OPERATION_MOVE
```
    The identifier used for "move" operations.
    
    See Also:
    
    Constant Field Values
  - OPERATION_COPY
```
public static final String OPERATION_COPY
```
    The identifier used for "copy" operations.
    
    See Also:
    
    Constant Field Values
  - 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:
    
    Constant Field Values
- Method Detail
  - 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

Class PatchOperation

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

FIELD_FIELD

FIELD_FROM

FIELD_OPERATION

FIELD_VALUE

OPERATION_ADD

OPERATION_INCREMENT

OPERATION_REMOVE

OPERATION_REPLACE

OPERATION_MOVE

OPERATION_COPY

OPERATION_TRANSFORM

Method Detail

add

add

increment

increment

remove

remove

remove

remove

replace

replace

move

move

copy

copy

transform

transform

operation

operation

copyOf

valueOf

valueOfList

getField

getFrom

getOperation

getValue

isAdd

isIncrement

isRemove

isReplace

isMove

isCopy

isTransform

toJsonValue

toString