Package org.apache.commons.io.channels

# Class ByteArraySeekableByteChannel

java.lang.Object
org.apache.commons.io.channels.ByteArraySeekableByteChannel

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`, `ByteChannel`, `Channel`, `ReadableByteChannel`, `SeekableByteChannel`, `WritableByteChannel`

public class ByteArraySeekableByteChannel extends Object implements SeekableByteChannel
A `SeekableByteChannel` implementation backed by a byte array.

When used for writing, the internal buffer grows to accommodate incoming data. The natural size limit is the value of `IOUtils.SOFT_MAX_ARRAY_LENGTH` and it's not possible to `set the position` or `truncate` to a value bigger than that. The raw internal buffer is accessed via `array()`.

Building a read-only channel from an existing byte array is supported with:

     try (ByteArraySeekableByteChannel channel = ByteArraySeekableByteChannel.builder()
                   .setByteArray(...)
                   .setOpenOptions(StandardOpenOption.READ)
                   .get()) {
                   // read from channel
     }

Since:
  2.21.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ByteArraySeekableByteChannel.Builder`
  Builds for `ByteArraySeekableByteChannel`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ByteArraySeekableByteChannel()`
  Constructs a new instance, with a default internal buffer capacity.
  `ByteArraySeekableByteChannel(int size)`
  Constructs a new instance, with an internal buffer of the given capacity, in bytes.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `byte[]`
  `array()`
  Gets the raw byte array backing this channel, this is not a copy.
  `static ByteArraySeekableByteChannel.Builder`
  `builder()`
  Constructs a new builder for `ByteArraySeekableByteChannel`.
  `void`
  `close()`
  `long`
  `getSize()`
  Like `size()` but never throws `ClosedChannelException`.
  `boolean`
  `isOpen()`
  `long`
  `position()`
  `SeekableByteChannel`
  `position(long newPosition)`
  `int`
  `read(ByteBuffer buf)`
  `long`
  `size()`
  `byte[]`
  `toByteArray()`
  Gets a copy of the data stored in this channel.
  `SeekableByteChannel`
  `truncate(long newSize)`
  `static ByteArraySeekableByteChannel`
  `wrap(byte[] bytes)`
  Constructs a new channel backed directly by the given byte array.
  `int`
  `write(ByteBuffer b)`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ByteArraySeekableByteChannel

    public ByteArraySeekableByteChannel()
    Constructs a new instance, with a default internal buffer capacity.

    The initial size and position of the channel are 0.

    See Also:
      - `ByteArrayOutputStream()`

  - ### ByteArraySeekableByteChannel

    public ByteArraySeekableByteChannel(int size)
    Constructs a new instance, with an internal buffer of the given capacity, in bytes.

    The initial size and position of the channel are 0.

    Parameters:
      `size` - Capacity of the internal buffer to allocate, in bytes.
    See Also:
      - `ByteArrayOutputStream(int)`

- ## Method Details

  - ### builder

    public static ByteArraySeekableByteChannel.Builder builder()
    Constructs a new builder for `ByteArraySeekableByteChannel`.
    Returns:
      a new builder for `ByteArraySeekableByteChannel`.
    Since:
      2.22.0

  - ### wrap

    public static ByteArraySeekableByteChannel wrap(byte[] bytes)
    Constructs a new channel backed directly by the given byte array.

    The channel initially contains the full contents of the array, with its size set to `bytes.length` and its position set to `0`.

    Reads and writes operate on the shared array. If a write operation extends beyond the current capacity, the channel will automatically allocate a larger backing array and copy the existing contents.

    Parameters:
      `bytes` - The byte array to wrap, must not be `null`
    Returns:
      A new channel that uses the given array as its initial backing store.
    Throws:
      `NullPointerException` - If `bytes` is `null`
    See Also:
      - `array()`
      - `ByteArrayInputStream(byte[])`

  - ### array

    public byte[] array()
    Gets the raw byte array backing this channel, this is not a copy.

    NOTE: The returned buffer is not aligned with containing data, use `size()` to obtain the size of data stored in the buffer.

    Returns:
      internal byte array.

  - ### close

    public void close()
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Channel`
    Specified by:
      `close` in interface `Closeable`

  - ### getSize

    public long getSize()
    Like `size()` but never throws `ClosedChannelException`.
    Returns:
      See `size()`.

  - ### isOpen

    public boolean isOpen()
    Specified by:
      `isOpen` in interface `Channel`

  - ### position

    public long position() throws ClosedChannelException
    Specified by:
      `position` in interface `SeekableByteChannel`
    Throws:
      `ClosedChannelException`

  - ### position

    public SeekableByteChannel position(long newPosition) throws IOException
    Specified by:
      `position` in interface `SeekableByteChannel`
    Throws:
      `IOException`

  - ### read

    public int read(ByteBuffer buf) throws IOException
    Specified by:
      `read` in interface `ReadableByteChannel`
    Specified by:
      `read` in interface `SeekableByteChannel`
    Throws:
      `IOException`

  - ### size

    public long size() throws ClosedChannelException
    Specified by:
      `size` in interface `SeekableByteChannel`
    Throws:
      `ClosedChannelException`

  - ### toByteArray

    public byte[] toByteArray()
    Gets a copy of the data stored in this channel.

    The returned array is a copy of the internal buffer, sized to the actual data stored in this channel.

    Returns:
      a new byte array containing the data stored in this channel.

  - ### truncate

    public SeekableByteChannel truncate(long newSize) throws ClosedChannelException
    Specified by:
      `truncate` in interface `SeekableByteChannel`
    Throws:
      `ClosedChannelException`

  - ### write

    public int write(ByteBuffer b) throws IOException
    Specified by:
      `write` in interface `SeekableByteChannel`
    Specified by:
      `write` in interface `WritableByteChannel`
    Throws:
      `IOException`