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>adoneitan@gmail.com</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 adoneitan@gmail.com
+ *
+ */
+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 adoneitan@gmail.com
+ */
+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 adoneitan@gmail.com
+ *
+ */
+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 adoneitan@gmail.com
+ * @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();
+}
+}