Further improvements to ObjectNode javadocs

Author: cowtowncoder

src/main/java/com/fasterxml/jackson/databind/node/ObjectNode.java

@@ -105,8 +105,8 @@ public Iterator<JsonNode> elements() {
     public JsonNode get(int index) { return null; }
 
     @Override
-    public JsonNode get(String fieldName) {
-        return _children.get(fieldName);
+    public JsonNode get(String propertyName) {
+        return _children.get(propertyName);
     }
 
     @Override
@@ -120,26 +120,26 @@ public JsonNode path(int index) {
     }
 
     @Override
-    public JsonNode path(String fieldName)
+    public JsonNode path(String propertyName)
     {
-        JsonNode n = _children.get(fieldName);
+        JsonNode n = _children.get(propertyName);
         if (n != null) {
             return n;
         }
         return MissingNode.getInstance();
     }
 
     @Override
-    public JsonNode required(String fieldName) {
-        JsonNode n = _children.get(fieldName);
+    public JsonNode required(String propertyName) {
+        JsonNode n = _children.get(propertyName);
         if (n != null) {
             return n;
         }
-        return _reportRequiredViolation("No value for property '%s' of `ObjectNode`", fieldName);
+        return _reportRequiredViolation("No value for property '%s' of `ObjectNode`", propertyName);
     }
 
     /**
-     * Method to use for accessing all fields (with both names
+     * Method to use for accessing all properties (with both names
      * and values) of this JSON Object.
      */
     @Override
@@ -213,13 +213,13 @@ public boolean equals(Comparator<JsonNode> comparator, JsonNode o)
      */
 
     @Override
-    public JsonNode findValue(String fieldName)
+    public JsonNode findValue(String propertyName)
     {
         for (Map.Entry<String, JsonNode> entry : _children.entrySet()) {
-            if (fieldName.equals(entry.getKey())) {
+            if (propertyName.equals(entry.getKey())) {
                 return entry.getValue();
             }
-            JsonNode value = entry.getValue().findValue(fieldName);
+            JsonNode value = entry.getValue().findValue(propertyName);
             if (value != null) {
                 return value;
             }
@@ -228,46 +228,46 @@ public JsonNode findValue(String fieldName)
     }
 
     @Override
-    public List<JsonNode> findValues(String fieldName, List<JsonNode> foundSoFar)
+    public List<JsonNode> findValues(String propertyName, List<JsonNode> foundSoFar)
     {
         for (Map.Entry<String, JsonNode> entry : _children.entrySet()) {
-            if (fieldName.equals(entry.getKey())) {
+            if (propertyName.equals(entry.getKey())) {
                 if (foundSoFar == null) {
                     foundSoFar = new ArrayList<JsonNode>();
                 }
                 foundSoFar.add(entry.getValue());
             } else { // only add children if parent not added
-                foundSoFar = entry.getValue().findValues(fieldName, foundSoFar);
+                foundSoFar = entry.getValue().findValues(propertyName, foundSoFar);
             }
         }
         return foundSoFar;
     }
 
     @Override
-    public List<String> findValuesAsText(String fieldName, List<String> foundSoFar)
+    public List<String> findValuesAsText(String propertyName, List<String> foundSoFar)
     {
         for (Map.Entry<String, JsonNode> entry : _children.entrySet()) {
-            if (fieldName.equals(entry.getKey())) {
+            if (propertyName.equals(entry.getKey())) {
                 if (foundSoFar == null) {
                     foundSoFar = new ArrayList<String>();
                 }
                 foundSoFar.add(entry.getValue().asText());
             } else { // only add children if parent not added
-                foundSoFar = entry.getValue().findValuesAsText(fieldName,
+                foundSoFar = entry.getValue().findValuesAsText(propertyName,
                     foundSoFar);
             }
         }
         return foundSoFar;
     }
 
     @Override
-    public ObjectNode findParent(String fieldName)
+    public ObjectNode findParent(String propertyName)
     {
         for (Map.Entry<String, JsonNode> entry : _children.entrySet()) {
-            if (fieldName.equals(entry.getKey())) {
+            if (propertyName.equals(entry.getKey())) {
                 return this;
             }
-            JsonNode value = entry.getValue().findParent(fieldName);
+            JsonNode value = entry.getValue().findParent(propertyName);
             if (value != null) {
                 return (ObjectNode) value;
             }
@@ -276,22 +276,22 @@ public ObjectNode findParent(String fieldName)
     }
 
     @Override
-    public List<JsonNode> findParents(String fieldName, List<JsonNode> foundSoFar)
+    public List<JsonNode> findParents(String propertyName, List<JsonNode> foundSoFar)
     {
         for (Map.Entry<String, JsonNode> entry : _children.entrySet()) {
-            if (fieldName.equals(entry.getKey())) {
+            if (propertyName.equals(entry.getKey())) {
                 if (foundSoFar == null) {
                     foundSoFar = new ArrayList<JsonNode>();
                 }
                 foundSoFar.add(this);
             } else { // only add children if parent not added
                 foundSoFar = entry.getValue()
-                    .findParents(fieldName, foundSoFar);
+                    .findParents(propertyName, foundSoFar);
             }
         }
         return foundSoFar;
     }
-    
+
     /*
     /**********************************************************
     /* Public API, serialization
@@ -364,7 +364,7 @@ public void serializeWithType(JsonGenerator g, SerializerProvider provider,
      */
 
     /**
-     * Method that will set specified field, replacing old value, if any.
+     * Method that will set specified property, replacing old value, if any.
      * Note that this is identical to {@link #replace(String, JsonNode)},
      * except for return value.
      *<p>
@@ -440,36 +440,36 @@ public <T extends JsonNode> T setAll(ObjectNode other)
      * Method for replacing value of specific property with passed
      * value, and returning value (or null if none).
      *
-     * @param fieldName Property of which value to replace
+     * @param propertyName Property of which value to replace
      * @param value Value to set property to, replacing old value if any
      * 
      * @return Old value of the property; null if there was no such property
      *   with value
      * 
      * @since 2.1
      */
-    public JsonNode replace(String fieldName, JsonNode value)
+    public JsonNode replace(String propertyName, JsonNode value)
     {
         if (value == null) { // let's not store 'raw' nulls but nodes
             value = nullNode();
         }
-        return _children.put(fieldName, value);
+        return _children.put(propertyName, value);
     }
 
     /**
-     * Method for removing field entry from this ObjectNode, and
+     * Method for removing property from this ObjectNode, and
      * returning instance after removal.
      *<p>
      * NOTE: co-variant return type since 2.10
      * 
-     * @return This node after removing entry (if any)
+     * @return This node after removing property (if any)
      * 
      * @since 2.1
      */
     @SuppressWarnings("unchecked")
-    public <T extends JsonNode> T without(String fieldName)
+    public <T extends JsonNode> T without(String propertyName)
     {
-        _children.remove(fieldName);
+        _children.remove(propertyName);
         return (T) this;
     }
 
@@ -479,16 +479,16 @@ public <T extends JsonNode> T without(String fieldName)
      *<p>
      * NOTE: co-variant return type since 2.10
      * 
-     * @param fieldNames Names of fields to remove
+     * @param propertyNames Names of properties to remove
      * 
      * @return This node after removing entries
      * 
      * @since 2.1
      */
     @SuppressWarnings("unchecked")
-    public <T extends JsonNode> T without(Collection<String> fieldNames)
+    public <T extends JsonNode> T without(Collection<String> propertyNames)
     {
-        _children.keySet().removeAll(fieldNames);
+        _children.keySet().removeAll(propertyNames);
         return (T) this;
     }
 
@@ -538,7 +538,7 @@ public JsonNode put(String propertyName, JsonNode value)
      * @param value Value to set to property (if and only if it had no value previously);
      *  if null, will be converted to a {@link NullNode} first.
      *
-     * @return Old value of the field, if any (in which case value was not changed);
+     * @return Old value of the property, if any (in which case value was not changed);
      *     null if there was no old value (in which case value is now set)
      *
      * @since 2.13
@@ -556,28 +556,28 @@ public JsonNode putIfAbsent(String propertyName, JsonNode value)
      * Will return previous value of the property, if such property existed;
      * null if not.
      * 
-     * @return Value of specified field, if it existed; null if not
+     * @return Value of specified property, if it existed; null if not
      */
-    public JsonNode remove(String fieldName) {
-        return _children.remove(fieldName);
+    public JsonNode remove(String propertyName) {
+        return _children.remove(propertyName);
     }
 
     /**
      * Method for removing specified field properties out of
      * this ObjectNode.
      * 
-     * @param fieldNames Names of fields to remove
+     * @param propertyNames Names of fields to remove
      * 
      * @return This node after removing entries
      */
-    public ObjectNode remove(Collection<String> fieldNames)
+    public ObjectNode remove(Collection<String> propertyNames)
     {
-        _children.keySet().removeAll(fieldNames);
+        _children.keySet().removeAll(propertyNames);
         return this;
     }
 
     /**
-     * Method for removing all field properties, such that this
+     * Method for removing all properties, such that this
      * ObjectNode will contain no properties after call.
      * 
      * @return This node after removing all entries
@@ -620,31 +620,31 @@ public JsonNode putAll(ObjectNode other) {
     }
 
     /**
-     * Method for removing all field properties out of this ObjectNode
+     * Method for removing all properties out of this ObjectNode
      * <b>except</b> for ones specified in argument.
      * 
-     * @param fieldNames Fields to <b>retain</b> in this ObjectNode
+     * @param propertyNames Fields to <b>retain</b> in this ObjectNode
      * 
      * @return This node (to allow call chaining)
      */
-    public ObjectNode retain(Collection<String> fieldNames)
+    public ObjectNode retain(Collection<String> propertyNames)
     {
-        _children.keySet().retainAll(fieldNames);
+        _children.keySet().retainAll(propertyNames);
         return this;
     }
 
     /**
-     * Method for removing all field properties out of this ObjectNode
+     * Method for removing all properties out of this ObjectNode
      * <b>except</b> for ones specified in argument.
      * 
-     * @param fieldNames Fields to <b>retain</b> in this ObjectNode
+     * @param propertyNames Fields to <b>retain</b> in this ObjectNode
      * 
      * @return This node (to allow call chaining)
      */
-    public ObjectNode retain(String... fieldNames) {
-        return retain(Arrays.asList(fieldNames));
+    public ObjectNode retain(String... propertyNames) {
+        return retain(Arrays.asList(propertyNames));
     }
-    
+
     /*
     /**********************************************************
     /* Extended ObjectNode API, mutators, typed
@@ -717,21 +717,25 @@ public ObjectNode putRawValue(String propertyName, RawValue raw) {
     }
 
     /**
+     * Method for setting value of a property to explicit {@code null} value.
+     * 
+     * @param propertyName Name of property to set.
+     *
      * @return This {@code ObjectNode} (to allow chaining)
      */
-    public ObjectNode putNull(String fieldName)
+    public ObjectNode putNull(String propertyName)
     {
-        _children.put(fieldName, nullNode());
+        _children.put(propertyName, nullNode());
         return this;
     }
 
     /**
-     * Method for setting value of a field to specified numeric value.
+     * Method for setting value of a property to specified numeric value.
      * 
      * @return This node (to allow chaining)
      */
-    public ObjectNode put(String fieldName, short v) {
-        return _put(fieldName, numberNode(v));
+    public ObjectNode put(String propertyName, short v) {
+        return _put(propertyName, numberNode(v));
     }
 
     /**