Package org.apache.juneau.marshall.stream

Interface RecordReader

All Superinterfaces:
AutoCloseable, Closeable
All Known Subinterfaces:
TokenReader
All Known Implementing Classes:
CborTokenReader, Json5lTokenReader, Json5TokenReader, JsonlTokenReader, JsonTokenReader, MsgPackTokenReader
public interface RecordReader extends Closeable
Public low-level whole-value pull cursor over a Juneau-formatted document.

Format-neutral cursor that yields one whole-value record per read(Class) call. Single-rooted formats (json, xml, bson, yaml, ...) degenerate to a one-record stream; multi-rooted formats (jsonl, csv, sse) expose each line / row / event as a separate record.

Usage:

try (RecordReader r = Json.DEFAULT.readRecords(input)) { while (r.canRead()) { Bean bean = r.read(Bean.class); process(bean); } }

Streaming quality:
  • isStreaming() == true — O(1)-memory streaming. FULL-token formats return a cursor that is also a TokenReader (the structural surface).
  • isStreaming() == false — buffered whole-value cursor (backed by RecordAdapter); read(Class) delegates to the format's existing parser and the structural surface is not available.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    canRead()
    Returns true if read(Class) can be called to produce another record.
    void
    close()
    Closes the underlying stream.
    boolean
    isStreaming()
    Returns true if this cursor is an O(1)-memory streaming cursor, or false if it is a buffered whole-value cursor (backed by RecordAdapter).
    default <T> Iterator<T>
    iterator(Class<T> type)
    Returns an Iterator view that yields each remaining record bound to the requested type.
    <T> T
    read(Class<T> type)
    Reads and returns the next record bound to the requested type.
    <T> T
    read(Type type, Type... args)
    Same as read(Class) but accepts a parameterized Type and optional type arguments (the same shape as Parser.read(Object, Type, Type...)).
    <T> T
    read(ClassMeta<T> type)
    Same as read(Class) but accepts a pre-resolved ClassMeta.
    default <T> Stream<T>
    stream(Class<T> type)
    Returns a Stream view that yields each remaining record bound to the requested type.

  • Method Details

    • canRead

      boolean canRead() throws IOException, ParseException
      Returns true if read(Class) can be called to produce another record.

      Single-rooted formats return true exactly once (for the root value), then false after the value has been consumed. Multi-rooted formats return true once per remaining record on the wire.

      Returns:
      true if a record is available; false at end of stream.
      Throws:
      IOException - If a problem occurred peeking at the underlying stream.
      ParseException - If the input is malformed for the format.

    • read

      <T> T read(Class<T> type) throws IOException, ParseException
      Reads and returns the next record bound to the requested type.
      Type Parameters:
      T - The expected return type.
      Parameters:
      type - The target Java type.
      Returns:
      The bound POJO.
      Throws:
      IOException - If a problem occurred reading from the underlying stream.
      ParseException - If the input is malformed for the format or cannot be bound to the type.
      IllegalStateException - If canRead() returned false.

    • read

      <T> T read(ClassMeta<T> type) throws IOException, ParseException
      Same as read(Class) but accepts a pre-resolved ClassMeta.
      Type Parameters:
      T - The expected return type.
      Parameters:
      type - The target type.
      Returns:
      The bound POJO.
      Throws:
      IOException - If a problem occurred reading from the underlying stream.
      ParseException - If the input is malformed or cannot be bound to the type.

    • read

      <T> T read(Type type, Type... args) throws IOException, ParseException
      Same as read(Class) but accepts a parameterized Type and optional type arguments (the same shape as Parser.read(Object, Type, Type...)).
      Type Parameters:
      T - The expected return type.
      Parameters:
      type - The target type.
      args - Optional type arguments for parameterized types.
      Returns:
      The bound POJO.
      Throws:
      IOException - If a problem occurred reading from the underlying stream.
      ParseException - If the input is malformed or cannot be bound to the type.

    • iterator

      default <T> Iterator<T> iterator(Class<T> type)
      Returns an Iterator view that yields each remaining record bound to the requested type.

      The iterator drains from this cursor; consuming both surfaces concurrently is not supported.

      Checked IOException / ParseException thrown by the underlying cursor are wrapped in an RuntimeParseException (carrying the typed cause) so they can surface through the Iterator API.

      Type Parameters:
      T - The element type.
      Parameters:
      type - The element type.
      Returns:
      An iterator over the remaining records.

    • stream

      default <T> Stream<T> stream(Class<T> type)
      Returns a Stream view that yields each remaining record bound to the requested type.
      Type Parameters:
      T - The element type.
      Parameters:
      type - The element type.
      Returns:
      A stream over the remaining records.

    • isStreaming

      boolean isStreaming()
      Returns true if this cursor is an O(1)-memory streaming cursor, or false if it is a buffered whole-value cursor (backed by RecordAdapter).
      Returns:
      true if this cursor streams; false if it buffers.

    • close

      void close() throws IOException
      Closes the underlying stream.

      Implementations should be idempotent — closing a closed reader is a no-op.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException