JsonDiff: more Javadoc; enforce non null arguments

Author: fge

src/main/java/com/github/fge/jsonpatch/diff2/DiffProcessor.java

@@ -33,6 +33,7 @@
 import java.util.List;
 import java.util.Map;
 
+// TODO: cleanup
 final class DiffProcessor
 {
     private static final Equivalence<JsonNode> EQUIVALENCE

src/main/java/com/github/fge/jsonpatch/diff2/JsonDiff.java

@@ -28,6 +28,9 @@
 import com.github.fge.jackson.NodeType;
 import com.github.fge.jackson.jsonpointer.JsonPointer;
 import com.github.fge.jsonpatch.JsonPatch;
+import com.github.fge.jsonpatch.JsonPatchMessages;
+import com.github.fge.msgsimple.bundle.MessageBundle;
+import com.github.fge.msgsimple.load.MessageBundles;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Equivalence;
 import com.google.common.collect.Maps;
@@ -50,11 +53,21 @@
  * patch for any other source/target combination than the one used to generate
  * the patch.</p>
  *
+ * <p>This class always performs operations in the following order: removals,
+ * additions and replacements. It then factors removal/addition pairs into
+ * move operations, or copy operations if a common element exists, at the same
+ * {@link JsonPointer pointer}, in both the source and destination.</p>
+ *
+ * <p>You can obtain a diff either as a {@link JsonPatch} directly or, for
+ * backwards compatibility, as a {@link JsonNode}.</p>
+ *
  * @since 1.2
  */
 @ParametersAreNonnullByDefault
 public final class JsonDiff
 {
+    private static final MessageBundle BUNDLE
+        = MessageBundles.getBundle(JsonPatchMessages.class);
     private static final ObjectMapper MAPPER = JacksonUtils.newMapper();
 
     private static final Equivalence<JsonNode> EQUIVALENCE
@@ -77,6 +90,8 @@ private JsonDiff()
     public static JsonPatch asJsonPatch(final JsonNode source,
         final JsonNode target)
     {
+        BUNDLE.checkNotNull(source, "common.nullArgument");
+        BUNDLE.checkNotNull(target, "common.nullArgument");
         final Map<JsonPointer, JsonNode> unchanged
             = getUnchangedValues(source, target);
         final DiffProcessor processor = new DiffProcessor(unchanged);
@@ -172,17 +187,17 @@ private static void generateArrayDiffs(final DiffProcessor processor,
         final int secondSize = target.size();
         final int size = Math.min(firstSize, secondSize);
 
-        for (int index = 0; index < size; index++)
-            generateDiffs(processor, pointer.append(index), source.get(index),
-                target.get(index));
-
         /*
          * Source array is larger; in this case, elements are removed from the
          * target; the index of removal is always the original arrays's length.
          */
         for (int index = size; index < firstSize; index++)
             processor.valueRemoved(pointer.append(size), source.get(index));
 
+        for (int index = 0; index < size; index++)
+            generateDiffs(processor, pointer.append(index), source.get(index),
+                target.get(index));
+
         // Deal with the destination array being larger...
         for (int index = size; index < secondSize; index++)
             processor.valueAdded(pointer.append("-"), target.get(index));

src/main/java/com/github/fge/jsonpatch/diff2/package-info.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2014, Francis Galiegue ([email protected])
+ *
+ * This software is dual-licensed under:
+ *
+ * - the Lesser General Public License (LGPL) version 3.0 or, at your option, any
+ *   later version;
+ * - the Apache Software License (ASL) version 2.0.
+ *
+ * The text of this file and of both licenses is available at the root of this
+ * project or, if you have the jar distribution, in directory META-INF/, under
+ * the names LGPL-3.0.txt and ASL-2.0.txt respectively.
+ *
+ * Direct link to the sources:
+ *
+ * - LGPL 3.0: https://www.gnu.org/licenses/lgpl-3.0.txt
+ * - ASL 2.0: http://www.apache.org/licenses/LICENSE-2.0.txt
+ */
+
+/**
+ * JSON "diff" implementation
+ *
+ * <p>The main class, {@link com.github.fge.jsonpatch.diff.JsonDiff}, does the
+ * reverse of what JSON Patch does: given two JSON values, it generates a patch
+ * (as JSON) to apply to the first node in order to obtain the second node.</p>
+ *
+ * <p>This implementation is able to factorize additions and removals into
+ * moves and copies.</p>
+ */
+package com.github.fge.jsonpatch.diff2;

src/main/resources/com/github/fge/jsonpatch/messages.properties

@@ -17,6 +17,7 @@
 # - ASL 2.0: http://www.apache.org/licenses/LICENSE-2.0.txt
 #
 
+common.nullArgument=argument cannot be null
 jsonPatch.deserFailed=unable to deserialize JSON input
 jsonPatch.nullInput=input cannot be null
 jsonPatch.nullValue=value cannot be null