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

tv.amwa.maj.model

## Interface RandomRawStorage

- All Superinterfaces:
    RawStorage

      public interface RandomRawStorage
      extends 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.

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

  Objects that implement RandomRawStorage also implement the following interfaces:

  - `RawStorage`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `getExtent()` Returns the number of bytes currently allocated to the storage.
    `long` | `getSize()` Returns the highest byte position in the storage that has been written so far.
    `boolean` | `isExtendable()` Returns `true` if the memory allocated to the storage can be dynamically extended; otherwise `false`.
    `byte[]` | `readAt(long position, int bufSize)` Attempts to read and return the given number of bytes (`bufSize`) from the storage at the given position.
    `void` | `setExtent(long extent)` Request the given capacity for the storage.
    `int` | `writeAt(long position, byte[] buffer)` Writes the given data buffer into the stream of the raw storage at the given position.

    - ### Methods inherited from interface tv.amwa.maj.model.RawStorage

      `isReadable, isWriteable, read, synchronize, write`

- - ### Method Detail

    - #### readAt

          @DataBuffer
          byte[] readAt(@UInt64
                                    long position,
                                    @UInt32
                                    int bufSize)
                             throws NotReadableException

      Attempts to read and return the given number of bytes (`bufSize`) from the storage at the given position. If the end of storage is encountered before the number of requested bytes can be read, the size of the array of bytes returned will be smaller than the one requested.

      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:
        `position` - Position in the storage from which data is read.
        `bufSize` - Number of bytes to read from the storage.
      Returns:
        Array of bytes read from the storage stream at the given position and up to the given size.
      Throws:
        `NotReadableException` - The storage is not open for reading.

    - #### writeAt

          @UInt32
          int writeAt(@UInt64
                              long position,
                              @DataBuffer
                              byte[] buffer)
                       throws NullPointerException,
                              OffsetSizeException,
                              NotWriteableException

      Writes the given data buffer into the stream of the raw storage at the given position.

      This call may fail if the capacity of this storage cannot be extended sufficiently to complete the request. The client can call `setExtent(long)` to attempt to reserve capacity for the storage. If the `setExtent(long)` call succeeds, subsequent write calls within requested that capacty are guaranteed to succeed.

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

      Parameters:
        `position` - Position in the storage into which the data is written.
        `buffer` - Buffer from which the data is written to the storage.
      Returns:
        Number of bytes actually written.
      Throws:
        `NullPointerException` - Argument is null.
        `OffsetSizeException` - It is not possible to extend the allocated size of this storage.
        `NotWriteableException` - This storage is not open for writing.

    - #### getSize

          @UInt64
          long getSize()

      Returns the highest byte position in the storage that has been written so far.

      Returns:
        Highest byte position in the storage that has been written so far.

    - #### isExtendable

          @Bool
          boolean isExtendable()

      Returns `true` if the memory allocated to the storage can be dynamically extended; otherwise `false`.

      Returns:
        Can the memory allocated to the storage be dynamically extended?

    - #### getExtent

          @UInt64
          long getExtent()

      Returns the number of bytes currently allocated to the storage.

      Returns:
        Number of bytes allocated to the storage.

    - #### setExtent

          void setExtent(@UInt64
                         long extent)
                  throws OffsetSizeException

      Request the given capacity for the storage. If successful, subequent calls to `RawStorage.write(byte[])` and `writeAt(long, byte[])` within the given capacity are gauranteed to succeed.

      Parameters:
        `extent` - Number of bytes capacity requested for the storage.
      Throws:
        `OffsetSizeException` - This storage has insufficient capacity to perform the write.

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