/**
 * Iterates over json1 which is intended to be a full representation of a complete JSON
 * structure.  It compares nodes on json1 against nodes on json2 which should contain
 * either the same identical structure of json1 or a subset of JSON structure contained
 * in json1.
 *
 * If identically named nodes on json1 and json2 vary in type (ObjectNode vs ArrayNode
 * for example) then an exception is thrown since json2 must not contain any additional
 * structure than what is found in json1.
 *
 * Explicit Null Node Handling Regardless of Node type:
 *
 * This pertains to the value of a node being explicity equal to null.  See further below
 * for handling of non-existent nodes
 *
 * If a node is null on json1 and not null on json2 then the node on json1 is set to the
 * value of the node on json2.
 *
 * If a node is not null on json1 and is null on json2 then the node on json1 is made null.
 *
 * Non-existent Node Handling:
 *
 * Since json1 is intended to be a full representation of a  complete JSON structure
 * nodes on json2 that don't exist on json1 are completely ignored.  Only if the same
 * node exists on both json1 and json2 will the structures be merged.
 *
 * ArrayNode Handling
 *
 * If the node being compared is an ArrayNode then the elements on json2 are iterated
 * over.  If the index on json1 exists on json1 then the two elements are merged.  If the
 * index doesn't exist on json1 then the element is added to the ArrayNode on json1.
 * Note: The existence of the element on json1 is determined by index and when an
 * element is added to json1 it's index increases by one.  That shouldn't be a problem
 * though as for there to ever be more elements in json2, the index pointer will always
 * be one larger than the max index of json1.
 *
 * ArrayNode Handling when json1 contains more elements than json2:
 *
 * If
 *
 * @param json1
 * @param json2
 * @return
 * @throws com.blackberry.bdp.common.exception.JsonMergeException
 */
public static JsonNode merge(JsonNode json1, JsonNode json2) throws JsonMergeException {
	Iterator<String> json1FieldNames = json1.fieldNames();
	while (json1FieldNames.hasNext()) {
		String json1Field = json1FieldNames.next();
		JsonNode json1Node = json1.get(json1Field);
		if (json1.getNodeType().equals(json2.getNodeType()) == false) {
			throw new JsonMergeException(String.format("json1 (%s) cannot be merged with json2 (%s)",
				 json1.getNodeType(), json2.getNodeType()));
		} else if (!json2.has(json1Field)) {
			LOG.info("Not comparing {} since it doesn't exist on json2", json1Field);
		} else if (json1Node.isNull() && json2.hasNonNull(json1Field)) {
			((ObjectNode) json1).replace(json1Field, json2.get(json1Field));
			LOG.info("explicitly null node {} on json1 replaced with non-null node on json2", json1Field);
		} else if (json1.hasNonNull(json1Field) && json2.get(json1Field).isNull()) {
			((ObjectNode) json1).replace(json1Field, json2.get(json1Field));
			LOG.info("non-null node {} on json1 replaced with explicitly null node on json2", json1Field);
		} else if (json1.isObject()) {
			LOG.info("Calling merge on Object {}", json1Field);
			merge(json1Node, json2.get(json1Field));
		} else if (json1 instanceof ObjectNode) {
			LOG.info("json1 is an instanceof ObjectNode");				;
			if (json2.get(json1Field) != null) {
				((ObjectNode) json1).replace(json1Field, json2.get(json1Field));
				LOG.info("json1 replaced {} with json2's field", json1Field);
			}
		} else if (json1.isArray()) {
			ArrayNode json1ArrayNode = (ArrayNode) json1.get(json1Field);
			ArrayNode json2ArrayNode = (ArrayNode) json2.get(json1Field);
			LOG.info("ArrayNode {} json1 has {} elements and json2 has {} elements",
				 json1Field, json1ArrayNode.size(), json2ArrayNode.size());
			int indexNo = 0;
			Iterator<JsonNode> json2Iter = json2ArrayNode.iterator();
			while (json2Iter.hasNext()) {
				JsonNode json2Element = json2Iter.next();
				if (!json1Node.has(indexNo)) {
					LOG.info("Need to merge ArrayNode {} element {}", json1Field, indexNo);
					merge(json1Node.get(indexNo), json2Element);
				} else {
					LOG.info("ArrayNode {} element {} not found on json1, adding", json1Field, indexNo);
					json1ArrayNode.add(json2Element);
				}
				indexNo++;
			}
			while (json1ArrayNode.size() > json2ArrayNode.size()) {
				int indexToRemove = json1ArrayNode.size() - 1;
				json1ArrayNode.remove(indexToRemove);
				LOG.info("ArrayNode {} index {} on json1 removed since greater than size of json2 ({})",
					 json1Field, indexToRemove, json2ArrayNode.size());
			}
		} else {
			throw new JsonMergeException(String.format("Cannot merge %s unknown type of %s",
				 json1Field, json1Node.getNodeType()));
		}
	}
	return json1;
}