GSON: .isJsonNull() question

isJsonNull() handles the case where the json element exists but has the json null value. get() returning Java null means that the element does not exist. Here's a simple example:

Json:

{
    "testElement": null
}

Java Code:

if (json.get("testElement").isJsonNull())
{
    System.out.println("testElement is json null value"); //This will print.
}
if (json.get("nonExistentElement") == null)
{
    System.out.println("nonExistentElement does not exist"); //This will print.
}

References:

JsonObject: public JsonElement get(String memberName) Returns the member with the specified name. Parameters: memberName - name of the member that is being requested. Returns: the member matching the name. Null if no such member exists.

https://www.javadoc.io/doc/com.google.code.gson/gson/2.8.0/com/google/gson/JsonObject.html

A value can be a string in double quotes, or a number, or true or false or null, or an object or an array. These structures can be nested.

https://www.json.org/json-en.html

Never mind my first answer below. I'd read the question too quickly.

It looks like this is a simple case of the documents lying -- or at least being misunderstood. Fortunately, code does not lie so easily and Gson is an open source project.

Here's JsonObject.get(String):

  /**
   * Returns the member with the specified name.
   *
   * @param memberName name of the member that is being requested.
   * @return the member matching the name. Null if no such member exists.
   */
  public JsonElement get(String memberName) {
    if (members.containsKey(memberName)) {
      JsonElement member = members.get(memberName);
      return member == null ? JsonNull.INSTANCE : member;
    }
    return null;
  }

and here's where members is populated:

  /**
   * Adds a member, which is a name-value pair, to self. The name must be a String, but the value
   * can be an arbitrary JsonElement, thereby allowing you to build a full tree of JsonElements
   * rooted at this node.
   *
   * @param property name of the member.
   * @param value the member object.
   */
  public void add(String property, JsonElement value) {
    if (value == null) {
      value = JsonNull.INSTANCE;
    }
    members.put($Gson$Preconditions.checkNotNull(property), value);
  }

Calls to add to members are made for every member defined in the Java class -- it's not based on what's in the JSON. (For those interested, the visitFieldsReflectively method in ReflectingFieldNavigator populates members.)

So, I suppose the confusion is surrounding the meaning of "member" in the clause "if no such member exists". Based on the code, I gather that the author of the JavaDoc was referring to a member defined in the Java class. To the casual user of the Gson API -- like myself -- I assumed that "member" referred to an object element in the JSON.

Now, is this issue clear?

====

First answer based on quick read of question (retained for useful links):

A null reference is not a JsonNull value. (value == null) is not the same as value.isJsonNull(). They are very different.

The docs describe that the call to JsonObject.get(String) returns "[n]ull if no such member exists." They do not say that JsonNull is returned.

The call to JsonElement.isJsonNull() is not checking whether the JsonElement reference is a null reference. In fact, if it were a null reference, calling a method on it would throw a NullPointerException. It's checking whether it's a JsonNull instance.