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 Summary

Fields

Modifier and Type	Field	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

Modifier and Type	Method	Description
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	add(JsonPointer field, Object value)	Creates a new "add" patch operation which will add the provided value(s) to the specified field.
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	copy(JsonPointer from, JsonPointer 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(String 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(JsonPointer 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(String from, String field)	Creates a new "move" patch operation which will move the value found at `from` to `path`.
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	operation(String operation, String field, Object value)	Creates a new patch operation having the specified operation type, field, and value(s).
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	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	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	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).
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).
JsonValue	toJsonValue()	Returns a JSON value representation of this patch operation.
String	toString()
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	transform(JsonPointer 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