nextSource

Returns the next value as a stream of UTF-8 bytes and consumes it.

The following program demonstrates how JSON bytes are returned from an enclosing stream astheir original bytes, including their original whitespace:

{@code * String json = "{\"a\": [4, 5 ,6.0, {\"x\":7}, 8], \"b\": 9}"; * JsonReader reader = JsonReader.of(new Buffer().writeUtf8(json)); * reader.beginObject(); * assertThat(reader.nextName()).isEqualTo("a"); * try (BufferedSource bufferedSource = reader.valueSource()) { * assertThat(bufferedSource.readUtf8()).isEqualTo("[4, 5 ,6.0, {\"x\":7}, 8]"); * } * assertThat(reader.nextName()).isEqualTo("b"); * assertThat(reader.nextInt()).isEqualTo(9); * reader.endObject(); * }

This reads an entire value: composite objects like arrays and objects are returned in theirentirety. The stream starts with the first character of the value (typically {@code [}, {, or {@code "}) and ends with the last character of the object (typically {@code ]},}, or {@code "}).

The returned source may not be used after any other method on this {@code JsonReader} iscalled. For example, the following code crashes with an exception:

{@code * JsonReader reader = ... * reader.beginArray(); * BufferedSource source = reader.valueSource(); * reader.endArray(); * source.readUtf8(); // Crash! * }

The returned bytes are not validated. This method assumes the stream is well-formed JSON andonly attempts to find the value's boundary in the byte stream. It is the caller'sresponsibility to check that the returned byte stream is a valid JSON value.

Closing the returned source does not close this reader.