Skip to content

Commit 1a6b90f

Browse files
author
Tamas Balog
committed
Add javadoc to a couple of methods
1 parent 6cb2c48 commit 1a6b90f

3 files changed

Lines changed: 147 additions & 17 deletions

File tree

‎src/main/java/org/skyscreamer/jsonassert/ValueMatcher.java‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,19 @@
11
package org.skyscreamer.jsonassert;
22

3+
/**
4+
* Represents a value matcher that can compare two objects for equality.
5+
*
6+
* @param <T> the object type to compare
7+
*/
38
public interface ValueMatcher<T> {
49

10+
/**
11+
* Compares the two provided objects whether they are equal.
12+
*
13+
* @param o1 the first object to check
14+
* @param o2 the object to check the first against
15+
* @return true if the objects are equal, false otherwise
16+
*/
517
boolean equal(T o1, T o2);
618

719
}

‎src/main/java/org/skyscreamer/jsonassert/comparator/JSONComparator.java‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,59 @@
1313
*/
1414
public interface JSONComparator {
1515

16+
/**
17+
* Compares two {@link JSONObject}s and returns the result of the comparison in a {@link JSONCompareResult} object.
18+
*
19+
* @param expected the expected JSON object
20+
* @param actual the actual JSON object
21+
* @return the result of the comparison
22+
* @throws JSONException
23+
*/
1624
JSONCompareResult compareJSON(JSONObject expected, JSONObject actual) throws JSONException;
1725

26+
/**
27+
* Compares two {@link JSONArray}s and returns the result of the comparison in a {@link JSONCompareResult} object.
28+
*
29+
* @param expected the expected JSON array
30+
* @param actual the actual JSON array
31+
* @return the result of the comparison
32+
* @throws JSONException
33+
*/
1834
JSONCompareResult compareJSON(JSONArray expected, JSONArray actual) throws JSONException;
1935

36+
/**
37+
* Compares two {@link JSONObject}s on the provided path represented by {@code prefix} and
38+
* updates the result of the comparison in the {@code result} {@link JSONCompareResult} object.
39+
*
40+
* @param prefix the path in the json where the comparison happens
41+
* @param expected the expected JSON object
42+
* @param actual the actual JSON object
43+
* @param result stores the actual state of the comparison result
44+
* @throws JSONException
45+
*/
2046
void compareJSON(String prefix, JSONObject expected, JSONObject actual, JSONCompareResult result) throws JSONException;
2147

48+
/**
49+
* Compares two {@link Object}s on the provided path represented by {@code prefix} and
50+
* updates the result of the comparison in the {@code result} {@link JSONCompareResult} object.
51+
*
52+
* @param prefix the path in the json where the comparison happens
53+
* @param expectedValue the expected value
54+
* @param actualValue the actual value
55+
* @param result stores the actual state of the comparison result
56+
* @throws JSONException
57+
*/
2258
void compareValues(String prefix, Object expectedValue, Object actualValue, JSONCompareResult result) throws JSONException;
2359

60+
/**
61+
* Compares two {@link JSONArray}s on the provided path represented by {@code prefix} and
62+
* updates the result of the comparison in the {@code result} {@link JSONCompareResult} object.
63+
*
64+
* @param prefix the path in the json where the comparison happens
65+
* @param expected the expected JSON array
66+
* @param actual the actual JSON array
67+
* @param result stores the actual state of the comparison result
68+
* @throws JSONException
69+
*/
2470
void compareJSONArray(String prefix, JSONArray expected, JSONArray actual, JSONCompareResult result) throws JSONException;
2571
}

‎src/main/java/org/skyscreamer/jsonassert/comparator/JSONCompareUtil.java‎

Lines changed: 89 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,58 @@
11
package org.skyscreamer.jsonassert.comparator;
22

3+
import java.util.ArrayList;
4+
import java.util.Collection;
5+
import java.util.HashMap;
6+
import java.util.HashSet;
7+
import java.util.Iterator;
8+
import java.util.List;
9+
import java.util.Map;
10+
import java.util.Set;
11+
import java.util.TreeSet;
12+
313
import org.json.JSONArray;
414
import org.json.JSONException;
515
import org.json.JSONObject;
616

7-
import java.util.*;
8-
917
/**
10-
* Utility class that contains Json manipulation methods
18+
* Utility class that contains Json manipulation methods.
1119
*/
1220
public final class JSONCompareUtil {
1321
private static Integer INTEGER_ONE = new Integer(1);
1422

15-
private JSONCompareUtil() {}
23+
private JSONCompareUtil() {
24+
}
1625

17-
public static Map<Object,JSONObject> arrayOfJsonObjectToMap(JSONArray array, String uniqueKey) throws JSONException {
26+
/**
27+
* Converts the provided {@link JSONArray} to a Map of {@link JSONObject}s where the key of each object
28+
* is the value at {@code uniqueKey} in each object.
29+
*
30+
* @param array the JSON array to convert
31+
* @param uniqueKey the key to map the JSON objects to
32+
* @return the map of {@link JSONObject}s from {@code array}
33+
* @throws JSONException
34+
*/
35+
public static Map<Object, JSONObject> arrayOfJsonObjectToMap(JSONArray array, String uniqueKey) throws JSONException {
1836
Map<Object, JSONObject> valueMap = new HashMap<Object, JSONObject>();
19-
for(int i = 0 ; i < array.length() ; ++i) {
20-
JSONObject jsonObject = (JSONObject)array.get(i);
37+
for (int i = 0; i < array.length(); ++i) {
38+
JSONObject jsonObject = (JSONObject) array.get(i);
2139
Object id = jsonObject.get(uniqueKey);
2240
valueMap.put(id, jsonObject);
2341
}
2442
return valueMap;
2543
}
2644

27-
45+
/**
46+
* Searches for the unique key of the {@code expected} JSON array.
47+
*
48+
* @param expected the array to find the unique key of
49+
* @return the unique key if there's any, otherwise null
50+
* @throws JSONException
51+
*/
2852
public static String findUniqueKey(JSONArray expected) throws JSONException {
2953
// Find a unique key for the object (id, name, whatever)
30-
JSONObject o = (JSONObject)expected.get(0); // There's at least one at this point
31-
for(String candidate : getKeys(o)) {
54+
JSONObject o = (JSONObject) expected.get(0); // There's at least one at this point
55+
for (String candidate : getKeys(o)) {
3256
if (isUsableAsUniqueKey(candidate, expected)) return candidate;
3357
}
3458
// No usable unique key :-(
@@ -41,7 +65,7 @@ public static String findUniqueKey(JSONArray expected) throws JSONException {
4165
*/
4266
public static boolean isUsableAsUniqueKey(String candidate, JSONArray array) throws JSONException {
4367
Set<Object> seenValues = new HashSet<Object>();
44-
for (int i = 0 ; i < array.length() ; i++) {
68+
for (int i = 0; i < array.length(); i++) {
4569
Object item = array.get(i);
4670
if (item instanceof JSONObject) {
4771
JSONObject o = (JSONObject) item;
@@ -62,50 +86,91 @@ public static boolean isUsableAsUniqueKey(String candidate, JSONArray array) thr
6286
return true;
6387
}
6488

89+
/**
90+
* Converts the given {@link JSONArray} to a list of {@link Object}s.
91+
*
92+
* @param expected the JSON array to convert
93+
* @return the list of objects from the {@code expected} array
94+
* @throws JSONException
95+
*/
6596
public static List<Object> jsonArrayToList(JSONArray expected) throws JSONException {
6697
List<Object> jsonObjects = new ArrayList<Object>(expected.length());
67-
for(int i = 0 ; i < expected.length() ; ++i) {
98+
for (int i = 0; i < expected.length(); ++i) {
6899
jsonObjects.add(expected.get(i));
69100
}
70101
return jsonObjects;
71102
}
72103

104+
/**
105+
* Returns whether all of the elements in the given array are simple values.
106+
*
107+
* @param array the JSON array to iterate through on
108+
* @return true if all the elements in {@code array} are simple values
109+
* @throws JSONException
110+
* @see #isSimpleValue(Object)
111+
*/
73112
public static boolean allSimpleValues(JSONArray array) throws JSONException {
74-
for(int i = 0 ; i < array.length() ; ++i) {
113+
for (int i = 0; i < array.length(); ++i) {
75114
if (!isSimpleValue(array.get(i))) {
76115
return false;
77116
}
78117
}
79118
return true;
80119
}
81120

121+
/**
122+
* Returns whether the given object is a simple value: not {@link JSONObject} and not {@link JSONArray}.
123+
*
124+
* @param o the object to inspect
125+
* @return true if {@code o} is a simple value
126+
*/
82127
public static boolean isSimpleValue(Object o) {
83128
return !(o instanceof JSONObject) && !(o instanceof JSONArray);
84129
}
85130

131+
/**
132+
* Returns whether all elements in {@code array} are {@link JSONObject} instances.
133+
*
134+
* @param array the array to inspect
135+
* @return true if all the elements in the given array are JSONObjects
136+
* @throws JSONException
137+
*/
86138
public static boolean allJSONObjects(JSONArray array) throws JSONException {
87-
for(int i = 0 ; i < array.length() ; ++i) {
139+
for (int i = 0; i < array.length(); ++i) {
88140
if (!(array.get(i) instanceof JSONObject)) {
89141
return false;
90142
}
91143
}
92144
return true;
93145
}
94146

147+
/**
148+
* Returns whether all elements in {@code array} are {@link JSONArray} instances.
149+
*
150+
* @param array the array to inspect
151+
* @return true if all the elements in the given array are JSONArrays
152+
* @throws JSONException
153+
*/
95154
public static boolean allJSONArrays(JSONArray array) throws JSONException {
96-
for(int i = 0 ; i < array.length() ; ++i) {
155+
for (int i = 0; i < array.length(); ++i) {
97156
if (!(array.get(i) instanceof JSONArray)) {
98157
return false;
99158
}
100159
}
101160
return true;
102161
}
103162

163+
/**
164+
* Collects all keys in {@code jsonObject}.
165+
*
166+
* @param jsonObject the {@link JSONObject} to get the keys of
167+
* @return the set of keys
168+
*/
104169
public static Set<String> getKeys(JSONObject jsonObject) {
105170
Set<String> keys = new TreeSet<String>();
106171
Iterator<?> iter = jsonObject.keys();
107-
while(iter.hasNext()) {
108-
keys.add((String)iter.next());
172+
while (iter.hasNext()) {
173+
keys.add((String) iter.next());
109174
}
110175
return keys;
111176
}
@@ -118,6 +183,13 @@ public static String formatUniqueKey(String key, String uniqueKey, Object value)
118183
return key + "[" + uniqueKey + "=" + value + "]";
119184
}
120185

186+
/**
187+
* Creates a cardinality map from {@code coll}.
188+
*
189+
* @param coll the collection of items to convert
190+
* @param <T> the type of elements in the input collection
191+
* @return the cardinality map
192+
*/
121193
public static <T> Map<T, Integer> getCardinalityMap(final Collection<T> coll) {
122194
Map count = new HashMap<T, Integer>();
123195
for (T item : coll) {

0 commit comments

Comments
 (0)