Interface MessageReader

All Superinterfaces:
AutoCloseable, Closeable
public sealed interface MessageReader extends Closeable

Reads values encoded in MessagePack from a channel, input stream, byte buffer, or MessageSink.Provider.

To create a new message reader, call of(java.nio.channels.ReadableByteChannel). To read values, call the various readXxx methods. To determine the next value's type, call nextType(). To close a message reader, call close(). Continued use of a closed message reader can result in data corruption.

For usage examples, see Reading data.

  • Method Details

    • of

      static MessageReader of(ReadableByteChannel channel)
      Returns a new message reader that reads from the given channel.
      Parameters:
      channel - the channel to read from
      Returns:
      a new message reader that reads from the given channel

    • of

      static MessageReader of(ReadableByteChannel channel, Consumer<MessageReader.OptionBuilder> optionHandler)
      Returns a new message reader with the given options that reads from the given channel.
      Parameters:
      channel - the channel to read from
      optionHandler - a handler that receives an MessageReader.OptionBuilder
      Returns:
      a new message reader with the given options that reads from the given channel

    • of

      static MessageReader of(InputStream stream)
      Returns a new message reader that reads from the given input stream.
      Parameters:
      stream - the input stream to read from
      Returns:
      a new message reader that reads from the given input stream

    • of

      static MessageReader of(InputStream stream, Consumer<MessageReader.OptionBuilder> optionHandler)
      Returns a new message reader with the given options that reads from the given input stream.
      Parameters:
      stream - the input stream to read from
      optionHandler - a handler that receives an MessageReader.OptionBuilder
      Returns:
      a new message reader with the given options that reads from the given input stream

    • of

      static MessageReader of(LeasedByteBuffer buffer)
      Returns a new message reader that reads from the given byte buffer.
      Parameters:
      buffer - the byte buffer to read from
      Returns:
      a new message reader that reads from the given byte buffer

    • of

      static MessageReader of(LeasedByteBuffer buffer, Consumer<MessageReader.OptionBuilder> optionHandler)
      Returns a new message reader with the given options that reads from the given byte buffer.
      Parameters:
      buffer - the byte buffer to read from
      optionHandler - a handler that receives an MessageReader.OptionBuilder
      Returns:
      a new message reader with the given options that reads from the given byte buffer

    • of

      static MessageReader of(ByteBuffer buffer)
      Returns a new message reader that reads from the given byte buffer.
      Parameters:
      buffer - the byte buffer to read from
      Returns:
      a new message reader that reads from the given byte buffer

    • of

      static MessageReader of(ByteBuffer buffer, Consumer<MessageReader.OptionBuilder> optionHandler)
      Returns a new message reader with the given options that reads from the given byte buffer.
      Parameters:
      buffer - the byte buffer to read from
      optionHandler - a handler that receives an MessageReader.OptionBuilder
      Returns:
      a new message reader with the given options that reads from the given byte buffer

    • of

      static MessageReader of(MessageSource.Provider provider)
      Returns a new message reader that reads from the given source provider.
      Parameters:
      provider - the source provider to read from
      Returns:
      a new message reader that reads from the given source provider

    • of

      static MessageReader of(MessageSource.Provider provider, Consumer<MessageReader.OptionBuilder> optionHandler)
      Returns a new message reader with the given options that reads from the given source provider.
      Parameters:
      provider - the source provider to read from
      optionHandler - a handler that receives an MessageReader.OptionBuilder
      Returns:
      a new message reader with the given options that reads from the given source provider

    • ofEmpty

      static MessageReader ofEmpty()
      Returns a new message reader that will throw EOFException when a value is read.
      Returns:
      a new message reader that will throw EOFException when a value is read

    • nextType

      MessageType nextType() throws IOException

      Reads the next value's type without consuming it.

      Consecutive calls to this method will return the same result.

      Returns:
      the next value's type
      Throws:
      EOFException - if the end of input is reached before the type has been read
      IOException - if an I/O error occurs

    • skipValue

      void skipValue() throws IOException
      Skips the next value.
      Throws:
      EOFException - if the end of input is reached before the value has been skipped
      IOException - if an I/O error occurs

    • skipValue

      void skipValue(int count) throws IOException
      Skips the next count values.
      Parameters:
      count - the number of values to skip
      Throws:
      EOFException - if the end of input is reached before the values have been skipped
      IOException - if an I/O error occurs

    • readNil

      void readNil() throws IOException
      Reads a nil (null) value.
      Throws:
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readBoolean

      boolean readBoolean() throws IOException
      Reads a boolean value.
      Returns:
      the boolean value read
      Throws:
      MxPackException.TypeMismatch - if the value read is not a boolean value
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readByte

      byte readByte() throws IOException
      Reads an integer value that fits into byte.
      Returns:
      the integer value read
      Throws:
      MxPackException.TypeMismatch - if the value read is not an integer value or does not fit into byte
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readShort

      short readShort() throws IOException
      Reads an integer value that fits into short.
      Returns:
      the integer value read
      Throws:
      MxPackException.TypeMismatch - if the value read is not an integer value or does not fit into short
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readInt

      int readInt() throws IOException
      Reads an integer value that fits into int.
      Returns:
      the integer value read
      Throws:
      MxPackException.TypeMismatch - if the value read is not an integer value or does not fit into int
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readLong

      long readLong() throws IOException
      Reads an integer value.
      Returns:
      the integer value read
      Throws:
      MxPackException.TypeMismatch - if the value read is not an integer value
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readFloat

      float readFloat() throws IOException
      Reads a floating point value that fits into float.
      Returns:
      the floating point value read
      Throws:
      MxPackException.TypeMismatch - if the value read is not a floating point value or does not fit into float
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readDouble

      double readDouble() throws IOException
      Reads a floating point value.
      Returns:
      the floating point value read
      Throws:
      MxPackException.TypeMismatch - if the value read is not a floating point value
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readTimestamp

      Instant readTimestamp() throws IOException
      Reads a timestamp value.
      Returns:
      the timestamp value read
      Throws:
      MxPackException.TypeMismatch - if the value read is not a timestamp value
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readString

      String readString() throws IOException

      Reads a string value.

      To read a string value as a sequence of bytes, call readStringHeader() followed by readPayload(java.nio.channels.WritableByteChannel, long).

      Returns:
      the string value read
      Throws:
      MxPackException.TypeMismatch - if the value read is not a string value
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readIdentifier

      String readIdentifier() throws IOException

      Reads a string value that is used as identifier.

      Calling this method has the same effect as calling readString() except that it indicates to this message reader that it may want to cache the returned value.

      Returns:
      the identifier read
      Throws:
      MxPackException.TypeMismatch - if the read value is not a string value
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • read

      <T> T read(MessageDecoder<T> decoder) throws IOException
      Reads and decodes a value.
      Type Parameters:
      T - the type of value to decode
      Parameters:
      decoder - the decoder to use
      Returns:
      the read and decoded value
      Throws:
      MxPackException.TypeMismatch - if the value read cannot be decoded with the given decoder
      EOFException - if the end of input is reached before the value has been read
      IOException - if an I/O error occurs

    • readArrayHeader

      int readArrayHeader() throws IOException

      Starts reading an array value.

      A call to this method, returning n, must be followed by n readXxx calls that read the array's elements.

      Returns:
      the number of elements in the array
      Throws:
      IOException - if an I/O error occurs

    • readMapHeader

      int readMapHeader() throws IOException

      Starts reading a map value.

      A call to this method, returning n, must be followed by n * 2 readXxx calls that alternately read the map's keys and values.

      Returns:
      the number of entries in the map
      Throws:
      IOException - if an I/O error occurs

    • readBinaryHeader

      int readBinaryHeader() throws IOException

      Starts reading a binary value.

      A call to this method, returning n, must be immediately followed by calls to readPayload(java.nio.channels.WritableByteChannel, long) that read n bytes in total.

      Returns:
      the length, in bytes, of the binary value
      Throws:
      IOException - if an I/O error occurs

    • readStringHeader

      int readStringHeader() throws IOException

      Starts reading a string value as a sequence of bytes.

      A call to this method, returning n, must be immediately followed by calls to readPayload(java.nio.channels.WritableByteChannel, long) that read n bytes in total.

      This method is a low-level alternative to readString().

      Returns:
      the length, in bytes, of the string
      Throws:
      IOException - if an I/O error occurs

    • readExtensionHeader

      ExtensionHeader readExtensionHeader() throws IOException

      Starts reading an extension value.

      A call to this method, returning an extension header with length n, must be immediately followed by calls to readPayload(java.nio.channels.WritableByteChannel, long) that read n bytes in total.

      Returns:
      the header of the extension value
      Throws:
      IOException - if an I/O error occurs

    • readPayload

      long readPayload(WritableByteChannel channel, long length) throws IOException

      Reads up to length bytes into the given channel.

      Fewer than length bytes may be read if this reader reaches the end of input.

      Parameters:
      channel - the channel to write to
      length - the number of bytes to read
      Returns:
      the actual number of bytes read
      Throws:
      IOException - if an I/O error occurs

    • readPayload

      long readPayload(OutputStream stream, long length) throws IOException

      Reads up to length bytes into the given output stream.

      Fewer than length bytes may be read if this reader reaches the end of input.

      Parameters:
      stream - the output stream to write to
      length - the number of bytes to read
      Returns:
      the actual number of bytes read
      Throws:
      IOException - if an I/O error occurs
      IOException - if an I/O error occurs

    • readPayload

      void readPayload(ByteBuffer buffer) throws IOException

      Reads up to Buffer.remaining() bytes into the given byte buffer.

      Fewer than Buffer.remaining() bytes may be read if this reader reaches the end of input.

      Parameters:
      buffer - the byte buffer to read into
      Throws:
      IOException - if an I/O error occurs

    • readUByte

      byte readUByte() throws IOException
      Reads an integer value that fits into byte interpreted as unsigned value.
      Returns:
      the integer value read
      Throws:
      IOException - if an I/O error occurs

    • readUShort

      short readUShort() throws IOException
      Reads an integer value that fits into short interpreted as unsigned value.
      Returns:
      the integer value read
      Throws:
      IOException - if an I/O error occurs

    • readUInt

      int readUInt() throws IOException
      Reads an integer value that fits into int interpreted as unsigned value.
      Returns:
      the integer value read
      Throws:
      IOException - if an I/O error occurs

    • readULong

      long readULong() throws IOException
      Reads an integer value that fits into a long interpreted as unsigned value.
      Returns:
      the integer value read
      Throws:
      IOException - if an I/O error occurs

    • close

      void close() throws IOException

      Closes this message reader.

      If this reader was created with of(ReadableByteChannel), this method calls Channel.close(). If this reader was created with of(InputStream), this method calls InputStream.close(). If this reader was created with of(LeasedByteBuffer), this method calls LeasedByteBuffer.close(). If this reader was created with of(MessageSource.Provider), this method calls MessageSource.Provider.close().

      Subsequent calls to this method have no effect. Continued use of a closed message reader can result in data corruption and may throw IllegalStateException.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - if an I/O error occurs