RawStorage (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.model

## Interface RawStorage

- All Known Subinterfaces:
    RandomRawStorage

      public interface RawStorage

  This interface is used by the toolkit to access storage in which `AAF files` are to be read and written. It is typically implemented by clients of `AAF file`. Note that some implementations are provided as a convenience to `AAF file` clients.

  When writing to a stream, clients should be aware that the stream's capacity may be limited. To insure that writes will not fail due to insufficient stream capacity, clients must implement `RandomRawStorage` and call `RandomRawStorage.setExtent(long)` to pre-allocate capacity in the stream. Writes done within the size specified to the most recent successful `RandomRawStorage.setExtent(long)` call are guaranteed to succeed.

  This method assumes that the storage has at least sequential access capability.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isReadable()` Returns `true` if the storage is readable; otherwise `false`.
    `boolean` | `isWriteable()` Returns `true` if this storage is writeable; otherwise `false`.
    `byte[]` | `read(int bufSize)` Reads the given number of bytes from the stream of the raw storage and returns them as a byte array.
    `void` | `synchronize()` Synchronizes any cached data of the raw storage object with the underlying storage.
    `int` | `write(byte[] buffer)` Writes the given bytes into the stream of the raw storage.

- - ### Method Detail

    - #### isReadable

          @Bool
          boolean isReadable()

      Returns `true` if the storage is readable; otherwise `false`.

      Returns:
        Is the storage readable?

    - #### read

          @DataBuffer
          byte[] read(@UInt32
                                  int bufSize)
                           throws NotReadableException

      Reads the given number of bytes from the stream of the raw storage and returns them as a byte array. If the end of the stream is encountered before the given number of bytes can be read, the output array will contain fewer bytes than specified.

      A call this method will advance the current position in the stream, as used by the next read operation, by the requested buffer size.

      Parameters:
        `bufSize` - Number of bytes to read from the raw storage stream.
      Returns:
        Buffer containing bytes read form raw storage stream.
      Throws:
        `NotReadableException` - The stream is not open for reading.

    - #### isWriteable

          @Bool
          boolean isWriteable()

      Returns `true` if this storage is writeable; otherwise `false`.

      Returns:
        Is the raw storage writeable?

    - #### write

          @UInt32
          int write(@DataBuffer
                            byte[] buffer)
                     throws NullPointerException,
                            NotWriteableException,
                            StreamFullException

      Writes the given bytes into the stream of the raw storage.

      This call may fail if the stream has insufficient capacity to complete the request. If this storage supports the `random raw storage` interface, the client can call `RandomRawStorage.setExtent(long)` to attempt to reserve capacity in the stream. If the call succeeds, subsequent calls to this method within that capacity are guaranteed to succeed.

      This call will advance the current position by the length of the given array of bytes.

      Parameters:
        `buffer` - Bytes to write to the stream of the raw storage.
      Returns:
        Number of bytes actually written.
      Throws:
        `NullPointerException` - Argument is null.
        `NotWriteableException` - The stream is not open for writing.
        `StreamFullException` - The stream has insufficient capacity to perform the write.

    - #### synchronize

          void synchronize()

      Synchronizes any cached data of the raw storage object with the underlying storage.

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.