uk.ac.starlink.table

## Interface ByteStore

- All Known Implementing Classes:
    AdaptiveByteStore, DiscardByteStore, FileByteStore, LimitByteStore, MemoryByteStore

      public interface ByteStore

  Defines a place where bytes can be written to and then read from.
  Since:
    11 Jul 2008

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Tidies up.
    `void` | `copy(java.io.OutputStream out)` Takes all the data written so far into this store's sink stream and copies it to a destination stream.
    `long` | `getLength()` Returns the number of bytes currently stored in this object.
    `java.io.OutputStream` | `getOutputStream()` Returns an output stream which can be used to write to the store.
    `java.nio.ByteBuffer[]` | `toByteBuffers()` Returns an array of byte buffers containing the bytes written to this store.

- - ### Method Detail

    - #### getOutputStream

          java.io.OutputStream getOutputStream()

      Returns an output stream which can be used to write to the store. May be called multiple times; always returns the same object. Note that this is not in general buffered - it is the responsibility of the user to take steps like wrapping it in a `BufferedOutputStream` for efficiency if required.
      Returns:
        data sink stream

    - #### getLength

          long getLength()

      Returns the number of bytes currently stored in this object.
      Returns:
        byte count

    - #### copy

          void copy(java.io.OutputStream out)
             throws java.io.IOException

      Takes all the data written so far into this store's sink stream and copies it to a destination stream. The output stream is not closed.
      Parameters:
        `out` - data destination stream
      Throws:
        `java.io.IOException`

    - #### toByteBuffers

          java.nio.ByteBuffer[] toByteBuffers()
                                       throws java.io.IOException

      Returns an array of byte buffers containing the bytes written to this store. The stored bytes are all of the bytes from the first buffer in the returned array, followed by all in the second, etc. In many cases the returned array will, and probably should, contain a single buffer, but if the written byte count exceeds `Integer.MAX_VALUE`, more than one will be required. The limit of each buffer indicates the number of bytes it contains.

      Usual usage will be to write all data, then call this method once; this model may affect implementation decisions about efficiency.

      Returns:
        byte buffer containing bytes written
      Throws:
        `java.io.IOException` - if there is an I/O error

    - #### close

          void close()

      Tidies up. Should be called when the data in this object is no longer required. This object may no longer be usable following a call to this method.