Package org.postgresql.util

# Interface ByteStreamWriter

All Known Implementing Classes:
  `ByteBufferByteStreamWriter`

public interface ByteStreamWriter
A class that can be used to set a byte array parameter by writing to an OutputStream.

The intended use case is wanting to write data to a byte array parameter that is stored off heap in a direct memory pool or in some other form that is inconvenient to assemble into a single heap-allocated buffer.

Users should write their own implementation depending on the original data source. The driver provides a built-in implementation supporting the `ByteBuffer` class, see `ByteBufferByteStreamWriter`.

Intended usage is to simply pass in an instance using `PreparedStatement.setObject(int, Object)`:

         int bufLength = someBufferObject.length();
         preparedStatement.setObject(1, new MyByteStreamWriter(bufLength, someBufferObject));

The length must be known ahead of the stream being written to.

This provides the application more control over memory management than calling `PreparedStatement.setBinaryStream(int, InputStream)` as with the latter the caller has no control over the buffering strategy.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `ByteStreamWriter.ByteStreamTarget`
  Provides a target to write bytes to.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `getLength()`
  Returns the length of the stream.
  `static ByteStreamWriter`
  `of(ByteBuffer... buf)`
  `void`
  `writeTo(ByteStreamWriter.ByteStreamTarget target)`
  Write the data to the provided `OutputStream`.

- ## Method Details

  - ### getLength

    int getLength()
    Returns the length of the stream.

    This must be known ahead of calling `writeTo(ByteStreamTarget)`.

    Returns:
      the number of bytes in the stream.

  - ### writeTo

    void writeTo(ByteStreamWriter.ByteStreamTarget target) throws IOException
    Write the data to the provided `OutputStream`.

    Should not write more than `getLength()` bytes. If attempted, the provided stream will throw an `IOException`.

    Parameters:
      `target` - the stream to write the data to
    Throws:
      `IOException` - if the underlying stream throws or there is some other error.

  - ### of

    static ByteStreamWriter of(ByteBuffer... buf)