wvlet.airframe.msgpack.spi.MessageSink.scala Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of airframe-msgpack_3 Show documentation
Pure-Scala MessagePack library
There is a newer version: 24.11.0
/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package wvlet.airframe.msgpack.spi

import java.io.{Flushable, IOException}

/**
  * Provides a buffered output stream that writes sequence of [[WriteBuffer]] instances.
  *
  * A Sink implementation has total control of the buffer memory so that it can reuse buffer memory, use buffer pools,
  * or use memory-mapped files.
  */
trait MessageSink extends AutoCloseable with Flushable {

  /**
    * Allocates the next buffer for writing MessagePack data.  This method returns an [[WriteBuffer]] instance that
    * has specified size of capacity at least. 
 When this method is called twice, the previously returned buffer is
    * no longer used. This method may be called twice without call of [[writeBuffer(int)]] in between. In this case, the
    * buffer should be discarded without flushing it to the output.
    *
    * @param minimumSize
    *   the minimum required buffer size to allocate
    * @return
    *   a Buffer instance with at least minimumSize bytes of capacity
    * @throws IOException
    */
  @throws[IOException]
  def next(minimumSize: Int): WriteBuffer

  /**
    * Writes the previously allocated buffer(s). 
 This method should write the buffer previously returned from
    * [[next(int)]] method until specified number of bytes. Once the entire buffer contents is totally written to the
    * sink, the buffer should not be used because a BufferSink implementation might reuse the buffer. 
 This method is
    * not always called for each [[next(int)]] call. In this case, the buffer should be discarded without flushing it to
    * the output when the next [[next(int)]] is called.
    *
    * @param length
    *   the number of bytes to write
    * @throws IOException
    */
  @throws[IOException]
  def writeBuffer(length: Int): Unit

  /**
    * Writes an external payload data. This method should follow semantics of OutputStream.
    *
    * @param buffer
    *   the data to write
    * @param offset
    *   the start offset in the data
    * @param length
    *   the number of bytes to write
    * @throws IOException
    */
  @throws[IOException]
  def write(buffer: Array[Byte], offset: Int, length: Int): Unit

  /**
    * Writes an external payload data.  Unlike [[write(byte[], int, int)]] method, the buffer is given - this
    * BufferSink implementation gets ownership of the buffer and may modify contents of the buffer. Contents of this
    * buffer won't be modified by the caller.
    *
    * @param buffer
    *   the data to add
    * @param offset
    *   the start offset in the data
    * @param length
    *   the number of bytes to add
    * @throws IOException
    */
  @throws[IOException]
  def add(buffer: Array[Byte], offset: Int, length: Int): Unit
}