Interface MessageWriter

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

Writes values encoded in MessagePack to a channel, output stream, MessageOutput, or MessageSink.Provider.

To create a new message writer, call of(java.nio.channels.WritableByteChannel). To write values, call the various write(boolean) and writeXxx methods. To flush a message writer, call flush(). To close a message writer, call close(). Continued use of a closed message writer can result in data corruption.

For usage examples, see Writing data.

  • Method Details

    • of

      static MessageWriter of(WritableByteChannel channel)
      Returns a new message writer that writes to the given channel.
      Parameters:
      channel - the channel to write to
      Returns:
      a new message writer that writes to the given channel

    • of

      static MessageWriter of(WritableByteChannel channel, Consumer<MessageWriter.OptionBuilder> optionHandler)
      Returns a new message writer with the given options that writes to the given channel.
      Parameters:
      channel - the channel to write to
      optionHandler - a handler that receives an MessageWriter.OptionBuilder
      Returns:
      a new message writer with the given options that writes to the given channel

    • of

      static MessageWriter of(OutputStream stream)
      Returns a new message writer that writes to the given output stream.
      Parameters:
      stream - the output stream to write to
      Returns:
      a new message writer that writes to the given output stream

    • of

      static MessageWriter of(OutputStream stream, Consumer<MessageWriter.OptionBuilder> optionHandler)
      Returns a new message writer with the given options that writes to the given output stream.
      Parameters:
      stream - the output stream to write to
      optionHandler - a handler that receives an MessageWriter.OptionBuilder
      Returns:
      a new message writer with the given options that writes to the given output stream

    • of

      static MessageWriter of(MessageOutput.Buffer output)
      Returns a new message writer that writes to the given buffer output.
      Parameters:
      output - the buffer output to write to
      Returns:
      a new message writer that writes to the given buffer output

    • of

      static MessageWriter of(MessageOutput.Buffer output, Consumer<MessageWriter.OptionBuilder> optionHandler)
      Returns a new message writer with the given options that writes to the given buffer output.
      Parameters:
      output - the buffer output to write to
      optionHandler - a handler that receives an MessageWriter.OptionBuilder
      Returns:
      a new message writer that writes to the given buffer output

    • of

      static MessageWriter of(MessageSink.Provider provider)
      Returns a new message writer that writes to the given sink provider.
      Parameters:
      provider - the sink provider to write to
      Returns:
      a new message writer that writes to the given sink provider

    • of

      static MessageWriter of(MessageSink.Provider provider, Consumer<MessageWriter.OptionBuilder> optionHandler)
      Returns a new message writer with the given options that writes to the given sink provider.
      Parameters:
      provider - the sink provider to write to
      optionHandler - a handler that receives an MessageWriter.OptionBuilder
      Returns:
      a new message writer with the given options that writes to the given sink provider

    • ofDiscarding

      static MessageWriter ofDiscarding()
      Returns a new message writer that discards any bytes written.
      Returns:
      a new message writer that discards any bytes written

    • ofDiscarding

      static MessageWriter ofDiscarding(ByteBuffer buffer)

      Returns a new message writer with the given underlying buffer that discards any bytes written.

      This method is intended for testing and benchmarking. It should not be used in production code.

      Parameters:
      buffer - the buffer to use
      Returns:
      a new message writer with the given underlying buffer that discards any bytes written

    • writeNil

      void writeNil() throws IOException
      Writes a nil (null) value.
      Throws:
      IOException - if an I/O error occurs

    • write

      void write(boolean value) throws IOException
      Writes a boolean value.
      Parameters:
      value - the boolean value to write
      Throws:
      IOException - if an I/O error occurs

    • write

      void write(byte value) throws IOException
      Writes an integer value that fits into byte.
      Parameters:
      value - the integer value to write
      Throws:
      IOException - if an I/O error occurs

    • write

      void write(short value) throws IOException
      Writes an integer value that fits into short.
      Parameters:
      value - the integer value to write
      Throws:
      IOException - if an I/O error occurs

    • write

      void write(int value) throws IOException
      Writes an integer value that fits into int.
      Parameters:
      value - the integer value to write
      Throws:
      IOException - if an I/O error occurs

    • write

      void write(long value) throws IOException
      Writes an integer value that fits into long.
      Parameters:
      value - the integer value to write
      Throws:
      IOException - if an I/O error occurs

    • write

      void write(float value) throws IOException
      Writes a floating point value that fits into float.
      Parameters:
      value - the floating point value to write
      Throws:
      IOException - if an I/O error occurs

    • write

      void write(double value) throws IOException
      Writes a floating point value that fits into double.
      Parameters:
      value - the floating point value to write
      Throws:
      IOException - if an I/O error occurs

    • write

      void write(Instant value) throws IOException
      Writes a timestamp value.
      Parameters:
      value - the timestamp value to write
      Throws:
      IOException - if an I/O error occurs

    • write

      void write(CharSequence string) throws IOException

      Writes a string value.

      To write a string value as a sequence of bytes, call writeStringHeader(int) followed by writePayload(java.nio.ByteBuffer).

      Parameters:
      string - the string value to write
      Throws:
      IOException - if an I/O error occurs

    • writeIdentifier

      void writeIdentifier(String identifier) throws IOException

      Writes a string value that is used as identifier.

      Calling this method has the same effect as calling write(CharSequence) except that it indicates to this message writer that it may want to cache the given value.

      Parameters:
      identifier - the identifier to write
      Throws:
      IOException - if an I/O error occurs

    • write

      <T> void write(T value, MessageEncoder<T> encoder) throws IOException
      Encodes and writes a value.
      Type Parameters:
      T - the type of value to encode and write
      Parameters:
      value - the value to encode and write
      encoder - the encoder to use
      Throws:
      IOException - if an I/O error occurs

    • writeArrayHeader

      void writeArrayHeader(int elementCount) throws IOException

      Starts writing an array value.

      A call to this method must be followed by elementCount writeXxx calls that write the array's elements.

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

    • writeMapHeader

      void writeMapHeader(int entryCount) throws IOException

      Starts writing a map value.

      A call to this method must be followed by entryCount * 2 writeXxx calls that alternately write the map's keys and values.

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

    • writeStringHeader

      void writeStringHeader(int length) throws IOException

      Starts writing a string value.

      A call to this method must be immediately followed by calls to writePayload(java.nio.ByteBuffer) that write length bytes in total.

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

      Parameters:
      length - the length, in bytes, of the string value's payload
      Throws:
      IOException - if an I/O error occurs

    • writeBinaryHeader

      void writeBinaryHeader(int length) throws IOException

      Starts writing a binary value.

      A call to this method must be immediately followed by calls to writePayload(java.nio.ByteBuffer) that write length bytes in total.

      Parameters:
      length - , the length, in bytes, of the binary value's payload
      Throws:
      IOException - if an I/O error occurs

    • writeExtensionHeader

      void writeExtensionHeader(int length, byte type) throws IOException
      Starts writing an extension value.
      Parameters:
      length - the length, in bytes, of the extension value
      type - the numeric identifier of the extension value's type
      Throws:
      IOException - if an I/O error occurs

    • writePayload

      void writePayload(ByteBuffer buffer) throws IOException

      Writes the remaining bytes of the given byte buffer.

      Calls to writePayload(java.nio.ByteBuffer) must be preceeded by a call to writeStringHeader(int), writeBinaryHeader(int), or writeExtensionHeader(int, byte).

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

    • writePayload

      void writePayload(ByteBuffer... buffers) throws IOException

      Writes the remaining bytes of the given byte buffers.

      Calls to writePayload(java.nio.ByteBuffer) must be preceeded by a call to writeStringHeader(int), writeBinaryHeader(int), or writeExtensionHeader(int, byte).

      Parameters:
      buffers - the byte buffers to write
      Throws:
      IOException - if an I/O error occurs

    • writePayload

      long writePayload(ReadableByteChannel channel, long length) throws IOException

      Writes up to length bytes read from the given channel.

      Fewer than length bytes may be written if the channel's end of input is reached.

      Calls to writePayload(java.nio.ByteBuffer) must be preceeded by a call to writeStringHeader(int), writeBinaryHeader(int), or writeExtensionHeader(int, byte).

      Parameters:
      channel - the channel to read from
      length - the number of bytes to write
      Returns:
      the actual number of bytes written (between 0 and length)
      Throws:
      IOException - if an I/O error occurs

    • writePayload

      long writePayload(InputStream stream, long length) throws IOException

      Writes up to length bytes read from the given input stream.

      Fewer than length bytes may be written if the input stream's end of input is reached.

      Calls to writePayload(java.nio.ByteBuffer) must be preceeded by a call to writeStringHeader(int), writeBinaryHeader(int), or writeExtensionHeader(int, byte).

      Parameters:
      stream - the input stream to read from
      length - the number of bytes to write
      Returns:
      the actual number of bytes written (between 0 and length)
      Throws:
      IOException - if an I/O error occurs

    • writeUnsigned

      void writeUnsigned(byte value) throws IOException
      Writes an integer value that fits into a byte interpreted as unsigned value.
      Parameters:
      value - the integer value to write
      Throws:
      IOException - if an I/O error occurs

    • writeUnsigned

      void writeUnsigned(short value) throws IOException
      Writes an integer value that fits into a short interpreted as unsigned value.
      Parameters:
      value - the integer value to write
      Throws:
      IOException - if an I/O error occurs

    • writeUnsigned

      void writeUnsigned(int value) throws IOException
      Writes an integer value that fits into an int interpreted as unsigned value.
      Parameters:
      value - the integer value to write
      Throws:
      IOException - if an I/O error occurs

    • writeUnsigned

      void writeUnsigned(long value) throws IOException
      Writes an integer value that fits into a long interpreted as unsigned value.
      Parameters:
      value - the integer value to write
      Throws:
      IOException - if an I/O error occurs

    • flush

      void flush() throws IOException

      Flushes this message writer.

      It is not necessary to explicitly flush a writer before closing it.

      If this writer was created with of(OutputStream), this method calls OutputStream.flush(). If this writer was created with of(MessageSink.Provider), this method calls MessageSink.Provider.close().

      Throws:
      IOException - if an I/O error occurs

    • close

      void close() throws IOException

      Closes this message writer.

      It is not necessary to explicitly flush a writer before closing it.

      If this writer was created with of(WritableByteChannel), this method calls Channel.close(). If this writer was created with of(OutputStream), this method calls OutputStream.close(). If this writer was created with of(MessageSink.Provider), this method calls MessageSink.Provider.close().

      Subsequent calls to this method have no effect. Continued use of a closed message writer 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