introduce helper classes to process a JSONObject and its nodes

.gitignore

@@ -20,3 +20,5 @@ json-smart/target/
 *.classpath
 *.project
 *.prefs
+*.iml
+.idea

json-smart/pom.xml

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>net.minidev</groupId>
     <artifactId>json-smart</artifactId>
-    <version>2.2.1</version>
+    <version>2.2.1-b-SNAPSHOT</version>
     <name>JSON Small and Fast Parser</name>
     <description>
         JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.
@@ -23,6 +23,12 @@
             <roles>
             </roles>
         </developer>
+        <developer>
+            <id>erav</id>
+            <name>Eitan Raviv</name>
+            <email>[email protected]</email>
+            <timezone>GMT+2</timezone>
+        </developer>
     </developers>
     <licenses>
         <license>

json-smart/src/main/java/net/minidev/json/actions/ElementRemover.java

@@ -0,0 +1,50 @@
+package net.minidev.json.actions;
+
+import net.minidev.json.JSONObject;
+import net.minidev.json.actions.traverse.JSONTraverser;
+import net.minidev.json.actions.traverse.RemoveElementsJsonAction;
+import net.minidev.json.actions.traverse.JSONTraverseAction;
+
+import java.util.*;
+
+/**
+ * <b>Removes key:value elements from every node of a {@link JSONObject} matching the list of user-specified elements.</b>
+ * <p>
+ * An element to remove must be specified as a key:value pair
+ * <p>
+ * <b>Usage Example:</b>
+ * <p>
+ * To remove the element k2:v2 from the {@link JSONObject} {k0:{k2:v2, k3:v3}, k1:{k2:v2, k4:v4}} use the remover like so:
+ * <pre>
+ * PathRemover pr = new PathRemover("k2.v2");
+ * JSONObject cleanObject = pr.remove(new JSONObject(...));
+ * </pre>
+ * The resulting object 'cleanObject' would be {k0:{k3:v3}, k1:{k4:v4}}
+ * <p>
+ * See unit tests for more examples
+ *
+ * @author [email protected]
+ *
+ */
+public class ElementRemover
+{
+	private Map<String, Object> elementsToRemove;
+
+	public ElementRemover(Map<String, Object> elementsToRemove)
+	{
+		this.elementsToRemove = elementsToRemove == null ? Collections.<String, Object>emptyMap() : elementsToRemove;
+	}
+
+	public ElementRemover(JSONObject elementsToRemove)
+	{
+		this.elementsToRemove = elementsToRemove == null ? Collections.<String, Object>emptyMap() : elementsToRemove;
+	}
+
+	public JSONObject remove(JSONObject objectToClean)
+	{
+		JSONTraverseAction strategy = new RemoveElementsJsonAction(this.elementsToRemove);
+		JSONTraverser traversal = new JSONTraverser(strategy);
+		traversal.traverse(objectToClean);
+		return (JSONObject) strategy.result();
+	}
+}

json-smart/src/main/java/net/minidev/json/actions/PathLocator.java

@@ -0,0 +1,74 @@
+package net.minidev.json.actions;
+
+import net.minidev.json.JSONArray;
+import net.minidev.json.JSONObject;
+import net.minidev.json.actions.path.DotDelimiter;
+import net.minidev.json.actions.path.PathDelimiter;
+import net.minidev.json.actions.traverse.JSONTraverser;
+import net.minidev.json.actions.traverse.LocatePathsJsonAction;
+import net.minidev.json.actions.traverse.JSONTraverseAction;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * <b>Searches for paths in a {@link JSONObject} and returns those found.</b>
+ * <p>
+ * Traverses the specified {@link JSONObject} searching for nodes whose paths (from the root down) match
+ * any of the user-specified paths. The paths that match are returned.
+ * <p>
+ * A path to locate must be specified in the n-gram format - a list of keys from the root down separated by dots:
+ * K0[[[[.K1].K2].K3]...]
+ * <br>
+ * A key to the right of a dot is a direct child of a key to the left of a dot. Keys with a dot in their name are
+ * not supported.
+ * <p>
+ *
+ * @author [email protected]
+ */
+public class PathLocator
+{
+	protected List<String> pathsToFind;
+	protected PathDelimiter pathDelimiter = new DotDelimiter().withAcceptDelimiterInNodeName(false);
+
+	public PathLocator(JSONArray pathsToFind)
+	{
+		if (pathsToFind == null || pathsToFind.isEmpty()) {
+			this.pathsToFind = Collections.emptyList();
+		}
+		else
+		{
+			this.pathsToFind = new ArrayList<String>();
+			for (Object s : pathsToFind) {
+				this.pathsToFind.add((String) s);
+			}
+		}
+	}
+
+	public PathLocator(List<String> pathsToFind)
+	{
+		this.pathsToFind = pathsToFind == null || pathsToFind.size() == 0 ?
+				Collections.<String>emptyList() : pathsToFind;
+	}
+
+	public PathLocator(String... pathsToFind)
+	{
+		this.pathsToFind = pathsToFind == null || pathsToFind.length == 0 ?
+				Collections.<String>emptyList() : Arrays.asList(pathsToFind);
+	}
+
+	public PathLocator with(PathDelimiter pathDelimiter) {
+		this.pathDelimiter = pathDelimiter;
+		return this;
+	}
+
+	public List<String> locate(JSONObject object)
+	{
+		JSONTraverseAction action = new LocatePathsJsonAction(this.pathsToFind, pathDelimiter);
+		JSONTraverser traversal = new JSONTraverser(action).with(pathDelimiter);
+		traversal.traverse(object);
+		return (List<String>) action.result();
+	}
+}

json-smart/src/main/java/net/minidev/json/actions/PathRemover.java

@@ -0,0 +1,74 @@
+package net.minidev.json.actions;
+
+import net.minidev.json.JSONArray;
+import net.minidev.json.JSONObject;
+import net.minidev.json.actions.traverse.JSONTraverser;
+import net.minidev.json.actions.traverse.RemovePathsJsonAction;
+import net.minidev.json.actions.traverse.JSONTraverseAction;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * <b>Removes branches of nodes from a {@link JSONObject} matching the list of user-specified paths.</b>
+ * <p>
+ * A path to remove must be specified in the n-gram format - a list of keys from the root down separated by dots:
+ * K0[[[[.K1].K2].K3]...]
+ * <br>
+ * A key to the right of a dot is a direct child of a key to the left of a dot. Keys with a dot in their name are
+ * not supported.
+ * <p>
+ * <b>Usage Example:</b>
+ * <p>
+ * To remove the field k1.k2 from the {@link JSONObject} {k1:{k2:v2}, k3:{k4:v4}} use the remover like so:
+ * <pre>
+ * PathRemover pr = new PathRemover("k1.k2");
+ * JSONObject cleanObject = pr.remove(new JSONObject(...));
+ * </pre>
+ * The resulting object 'cleanObject' would be {k1:{k3:{k4:v4}}}
+ * <p>
+ * See unit tests for more examples
+ *
+ * @author [email protected]
+ *
+ */
+public class PathRemover
+{
+	protected List<String> pathsToRemove;
+
+	public PathRemover(JSONArray pathsToRemove)
+	{
+		if (pathsToRemove == null || pathsToRemove.isEmpty()) {
+			this.pathsToRemove = Collections.emptyList();
+		}
+		else
+		{
+			this.pathsToRemove = new ArrayList<String>();
+			for (Object s : pathsToRemove) {
+				this.pathsToRemove.add((String) s);
+			}
+		}
+	}
+
+	public PathRemover(List<String> pathsToRemove)
+	{
+		this.pathsToRemove = pathsToRemove == null || pathsToRemove.size() == 0 ?
+				Collections.<String>emptyList() : pathsToRemove;
+	}
+
+	public PathRemover(String... pathsToRemove)
+	{
+		this.pathsToRemove = pathsToRemove == null || pathsToRemove.length == 0 ?
+				Collections.<String>emptyList() : Arrays.asList(pathsToRemove);
+	}
+
+	public JSONObject remove(JSONObject objectToClean)
+	{
+		JSONTraverseAction strategy = new RemovePathsJsonAction(this.pathsToRemove);
+		JSONTraverser traversal = new JSONTraverser(strategy);
+		traversal.traverse(objectToClean);
+		return (JSONObject) strategy.result();
+	}
+}

json-smart/src/main/java/net/minidev/json/actions/PathReplicator.java

@@ -0,0 +1,76 @@
+package net.minidev.json.actions;
+
+import net.minidev.json.JSONArray;
+import net.minidev.json.JSONObject;
+import net.minidev.json.actions.navigate.CopyPathsAction;
+import net.minidev.json.actions.navigate.JSONNavigator;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.LinkedList;
+import java.util.List;
+
+/**
+ * <b>Creates a copy of a {@link JSONObject} consisting only of the nodes on the user-specified paths.</b>
+ * <p>
+ * Paths that do not exist in the specified object are ignored silently. Specifying an empty list of paths
+ * to copy or only non-existent paths will result in an empty object being returned.
+ * <p>
+ * A path to copy must be specified in the n-gram format - a list of keys from the root down separated by dots:
+ * K0[[[[.K1].K2].K3]...]
+ * <br>
+ * A key to the right of a dot is a direct child of a key to the left of a dot. Keys with a dot in their name are
+ * not supported.
+ * <p>
+ * <b> Sample usage:</b>
+ * <p>
+ * To replicate the branch k1.k2 from {k1:{k2:v2}, k3:{k4:v4}} use the {@link PathReplicator} like so:
+ * <pre>
+ * PathReplicator pr = new {@link PathReplicator}("k1.k2")
+ * JSONObject copiedObject = pr.copy(new JSONObject(...))
+ * </pre>
+ * The resulting object 'copiedObject' would be {k1:{k2:v2}}
+ * <p>
+ * see unit tests for more examples
+ *
+ * @author [email protected]
+ * @since 15 March 2016.
+ */
+public class PathReplicator
+{
+	protected List<String> pathsToCopy;
+
+	public PathReplicator(JSONArray pathsToCopy)
+	{
+		if (pathsToCopy == null || pathsToCopy.isEmpty()) {
+			this.pathsToCopy = Collections.emptyList();
+		}
+		else
+		{
+			this.pathsToCopy = new LinkedList<String>();
+			for (Object s : pathsToCopy) {
+				this.pathsToCopy.add((String) s);
+			}
+		}
+	}
+
+	public PathReplicator(List<String> pathsToCopy)
+	{
+		this.pathsToCopy = pathsToCopy == null || pathsToCopy.size() == 0 ?
+				Collections.<String>emptyList() : pathsToCopy;
+	}
+
+	public PathReplicator(String... pathsToCopy)
+	{
+		this.pathsToCopy = pathsToCopy == null || pathsToCopy.length == 0 ?
+				Collections.<String>emptyList() : new LinkedList<String>(Arrays.asList(pathsToCopy));
+	}
+
+	public JSONObject replicate(JSONObject sourceObj) throws Exception
+	{
+		CopyPathsAction s = new CopyPathsAction();
+		JSONNavigator n = new JSONNavigator(s, pathsToCopy);
+		n.nav(sourceObj);
+		return (JSONObject) s.result();
+	}
+}