JsonMergeOption (JSON Merge Core 1.2.4 API)

java.lang.Object
- net.obvj.jsonmerge.JsonMergeOption

public final class JsonMergeOption
extends Object

An object that contains parameters about how to merge a specific path of a JSON document.

Use onPath(String) to initialize the construction of a JsonMergeOption with a specific document path, then let the API guide you through the additional builder methods to finalize the construction of the desired merge option.

Examples:

  JsonMergeOption.onPath("$.parameters")
          .findObjectsIdentifiedBy("name")
          .thenPickTheHigherPrecedenceOne();

  JsonMergeOption.onPath("$.files")
          .findObjectsIdentifiedBy("id", "version")
          .thenDoADeepMerge();

  JsonMergeOption.onPath("$.files")
          .addDistinctObjectsOnly();

  JsonMergeOption.onPath("$.files")
          .addAll();

Since:: 1.0.0
Author:: oswaldo.bapvic.jr

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`JsonMergeOption.Builder` A builder for `JsonMergeOption`, with the document path already set.
`static class`	`JsonMergeOption.BuilderWithKeys` An intermediary `JsonMergeOption` build stage that is applicable when one or more distinct keys are specified for a given document path.

Field Summary

Fields
Modifier and Type Field and Description

static JsonMergeOption DEFAULT
The default merge option.

Fields
Modifier and Type	Field and Description
`static JsonMergeOption`	`DEFAULT` The default merge option.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static JsonMergeOption`	`distinctKey(String jsonPath, String key)` Deprecated. Use `onPath(String)` instead
`static JsonMergeOption`	`distinctKeys(String jsonPath, String... keys)` Deprecated. Use `onPath(String)` instead
`boolean`	`equals(Object object)` Indicates whether some other object is "equal to" this one.
`List<String>`	`getKeys()` Returns a list of keys to be considered for distinct JSON objects identification inside the array represented by `getPath()`.
`JsonPathExpression`	`getPath()` Returns a `JsonPath` expression that represents a specific path of the JSON document to receive special handling during the merge
`int`	`hashCode()` Returns a hash code value for the object.
`boolean`	`isDeepMerge()` Returns a flag indicating whether or not to do a deep merge of the elements inside the document path represented by `getPath()`.
`boolean`	`isDistinctObjectsOnly()` Returns a flag indicating whether or not to check for duplicate objects before adding them during the merge of the array path represented by `getPath()`.
`static JsonMergeOption.Builder`	`onPath(String jsonPath)` Initializes the construction of a `JsonMergeOption` for the document path determined by the given `JsonPath` expression.
`String`	`toString()` Returns a string representation of this `JsonMergeOption`.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT
```
public static final JsonMergeOption DEFAULT
```
    The default merge option.
    
    Since:
    
    1.1.0
- Method Detail
  - distinctKey
```
@Deprecated
public static JsonMergeOption distinctKey(String jsonPath,
                                                       String key)
```
    Deprecated. Use onPath(String) instead
    Specifies a distinct key for objects inside an array identified by a given JsonPath expression.
    For example, consider the following document:
    { "params": [ { "param": "name", "value": "John Doe" }, { "param": "age", "value": 33 } ] }
    A MergeOption of key "param" associated with the JsonPath expression "$.params" tells the algorithm to check for distinct objects identified by the same value inside the "param" field during the merge of the "$.params" array.
    In other words, if two JSON documents contain different objects identified by the same key inside that array, then only the object from the highest-precedence JSON document will be selected.
    A JsonPath expression can be specified using either dot- or bracket-notation, but complex expressions containing filters, script, subscript, or union operations, are not supported.
    Parameters:
    
    jsonPath - a JsonPath expression that identifies the array; not empty
    
    key - the key to be considered unique for objects inside an array
    
    Returns:
    
    a new JsonMergeOption with the specified pair of distinct path and key
    
    Throws:
    
    IllegalArgumentException - if one of the parameters is null or blank
    
    com.jayway.jsonpath.InvalidPathException - if the specified JsonPath expression is invalid
  - distinctKeys
```
@Deprecated
public static JsonMergeOption distinctKeys(String jsonPath,
                                                        String... keys)
```
    Deprecated. Use onPath(String) instead
    Specifies one or more distinct keys for objects inside an array identified by a given JsonPath expression.
    For example, consider the following document:
    { "files": [ { "id": "d2b638be-40d2-4965-906e-291521f8a19d", "version": "1", "date": "2022-07-07T10:42:21" }, { "id": "d2b638be-40d2-4965-906e-291521f8a19d", "version": "2", "date": "2022-08-06T09:40:01" }, { "id": "9570cc646-1586-11ed-861d-0242ac120002", "version": "1", "date": "2022-08-06T09:51:40" } ] }
    A MergeOption of keys "id" and "version" associated with the JsonPath expression "$.files" tells the algorithm to check for distinct objects identified by the same values in both fields "id" and "version" during the merge of the "$.files" array.
    In other words, if two JSON documents contain different objects identified by the same keys inside that array, then only the object from the highest-precedence JSON document will be selected.
    A JsonPath expression can be specified using either dot- or bracket-notation, but complex expressions containing filters, script, subscript, or union operations, are not supported.
    Parameters:
    
    jsonPath - a JsonPath expression that identifies the array; not empty
    
    keys - one or more keys to be considered unique for objects inside an array
    
    Returns:
    
    a new JsonMergeOption with the specified pair of path and distinct keys
    
    Throws:
    
    IllegalArgumentException - if one of the parameters is null or blank
    
    com.jayway.jsonpath.InvalidPathException - if the specified JsonPath expression is invalid
  - onPath
```
public static JsonMergeOption.Builder onPath(String jsonPath)
```
    Initializes the construction of a JsonMergeOption for the document path determined by the given JsonPath expression.
    A JsonPath expression can be specified using either dot- or bracket-notation, but complex expressions containing filters, script, subscript, or union operations, are not fully supported.
    Examples of valid expressions:
    - Using dot-notation
      $.sites $.sites[*].users $.sites[*].users[*].preferences
    - Using bracket-notation
      $['sites'] $['sites'][*]['users'] $['sites'][*]['users'][*]['preferences']
    Sample JSON:
```
 {
   "sites": [
     {
       "id": "europe-1",
       "users": [
         {
           "email": "camillelawson@zolarex.com",
           "preferences": [
             {
               "key": "theme",
               "value": "light"
             }
           ]
         }
       ]
     }
   ]
 }
 
```
    Parameters:
    
    jsonPath - a JsonPath expression that identifies the document part that should receive special handling during the merge; not empty
    
    Returns:
    
    a JsonMergeOption builder initialized with the specified JsonPath
    
    Throws:
    
    IllegalArgumentException - if the specified expression is null or empty
    
    com.jayway.jsonpath.InvalidPathException - if the specified JsonPath expression is invalid
    
    Since:
    
    1.1.0
    
    See Also:
    
    JsonPathExpression
  - getPath
```
public JsonPathExpression getPath()
```
    Returns a JsonPath expression that represents a specific path of the JSON document to receive special handling during the merge
    
    Returns:
    
    a JsonPathExpression; not null
    
    Since:
    
    1.1.0
  - getKeys
```
public List<String> getKeys()
```
    Returns a list of keys to be considered for distinct JSON objects identification inside the array represented by getPath().
    
    Returns:
    
    a list containing keys, or an empty list; never null
    
    Since:
    
    1.1.0
  - isDeepMerge
```
public boolean isDeepMerge()
```
    Returns a flag indicating whether or not to do a deep merge of the elements inside the document path represented by getPath().
    
    Returns:
    
    a flag indicating whether or not to do a deep merge of the path
    
    Since:
    
    1.1.0
  - isDistinctObjectsOnly
```
public boolean isDistinctObjectsOnly()
```
    Returns a flag indicating whether or not to check for duplicate objects before adding them during the merge of the array path represented by getPath().
    
    Returns:
    
    a flag indicating whether or not to avoid duplicate objects during the merge
    
    Since:
    
    1.1.0
  - toString
```
public String toString()
```
    Returns a string representation of this JsonMergeOption.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a string representation of this object
    
    Since:
    
    1.1.0
  - hashCode
```
public int hashCode()
```
    Returns a hash code value for the object.
    
    Overrides:
    
    hashCode in class Object
    
    Since:
    
    1.2.0
  - equals
```
public boolean equals(Object object)
```
    Indicates whether some other object is "equal to" this one.
    Two JsonMergeOptions will be considered equal if they share the same path.
    
    Overrides:
    
    equals in class Object
    
    Since:
    
    1.2.0

Class JsonMergeOption

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT

Method Detail

distinctKey

distinctKeys

onPath

getPath

getKeys

isDeepMerge

isDistinctObjectsOnly

toString

hashCode

equals