JsonReader.hasNext() returns true at END_DOCUMENT

[Cerebrum2]

JsonReader.hasNext() will return true if we are at the end of the document
(reader.peek() == JsonToken.END_DOCUMENT)

[DarthGizka]

It is not so much that hasNext() returns true (which seems correct anyway) as the fact that skipValue() fails to skip END_DOCUMENT:

@Test
public void skipValue_does_not_skip_END_DOCUMENT ()
    throws IOException
{
    try (JsonReader jsonReader = new JsonReader(new StringReader("{}")))
    {
        int endOfDocumentSeen = 0;

        for ( ; jsonReader.hasNext() && (endOfDocumentSeen < 3); jsonReader.skipValue())
        {
            JsonToken jt = jsonReader.peek();

            System.out.println(jt + (jt == JsonToken.END_DOCUMENT ? " #" + endOfDocumentSeen++ : ""));
        }

        assertNotEquals(1, endOfDocumentSeen);
    }
}

In other words, hasNext() and skipValue() seem to follow different, incompatible logical models. The fact that skipValue() cannot skip past END_DOCUMENT bears mentioning in the documentation - although I wager that everyone who walks into that trap cannot but notice the resulting infinite loop. Hence one could say that the behaviour is self-documenting in the sense that it becomes blatantly obvious whenever it matters.

The JavaDoc examples neatly skirt the problem by imposing prior assumptions on the JSON to be processed, by bracketing all loops with things like beginObject()/endObject() or beginArray()/endArray().