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

tv.amwa.maj.industry

## Interface Stream

- All Known Implementing Classes:
    AAFStream, FileStream, MemoryResidentStream, MXFStream, XMLStream

      public interface Stream

  Read and write access to stream type data.

  See Also:
    `EssenceData.getEssenceStream()`, `TypeDefinitionStream`, `TypeDefinitions.Stream`, `MemoryResidentStream`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `Stream` | `clone()` Create a cloned copy of the underlying stream accessor class.
    `void` | `close()` Close the stream and release any associated systems resources.
    `ByteOrder` | `getByteOrder()` Returns the byte order of the stream.
    `long` | `getLength()` Returns the length of the stream, measured in bytes.
    `long` | `getLimit()` Gets the limit position beyond which content cannot be read or written.
    `long` | `getPosition()` Returns the current position for reading from or writing to the stream.
    `URI` | `getStreamURI()` Returns the URI that specifies the location of this stream.
    `ByteBuffer` | `read(int noOfBytes)` Read the number of bytes requested from the stream into a newly created byte buffer.
    `void` | `setLimit(long limit)` Sets the limit position beyond which content cannot be read or written.
    `void` | `setPosition(long position)` Sets the current position for reading from or writing to the stream.
    `int` | `write(ByteBuffer buffer)` Write the number of bytes requested to the stream from the given byte buffer.

- - ### Method Detail

    - #### getPosition

          long getPosition()
                    throws IOException

      Returns the current position for reading from or writing to the stream.

      Returns:
        Current position for reading from or writing to the stream.
      Throws:
        `IOException` - An IO problem occurred when trying to access the stream.
      See Also:
        `setPosition(long)`

    - #### setPosition

          void setPosition(long position)
                    throws IllegalArgumentException,
                           IOException

      Sets the current position for reading from or writing to the stream.

      Parameters:
        `position` - Current position for reading from or writing to the stream.
      Throws:
        `IllegalArgumentException` - Cannot set a stream position to a negative value or beyond the limit set for the stream.
        `IOException` - An IO problem occurred when trying to access the stream.
      See Also:
        `getPosition()`, `getLimit()`

    - #### getLength

          long getLength()
                  throws IOException

      Returns the length of the stream, measured in bytes.

      Returns:
        Length of the stream, measured in bytes.
      Throws:
        `IOException` - An IO problem occurred when trying to access the stream.

    - #### getLimit

          long getLimit()
                 throws IOException

      Gets the limit position beyond which content cannot be read or written.

      Returns:
        Limit position beyond which content cannot be read or written.
      Throws:
        `IOException` - An IO problem occurred when trying to access the stream.
      See Also:
        `setLimit(long)`

    - #### setLimit

          void setLimit(long limit)
                 throws IllegalArgumentException

      Sets the limit position beyond which content cannot be read or written.

      Parameters:
        `limit` - Limit position beyond which content cannot be read or written.
      Throws:
        `IllegalArgumentException` - The limit position cannot set beyond the end of the stream.

    - #### read

          ByteBuffer read(int noOfBytes)
                   throws EndOfDataException,
                          IOException,
                          IllegalArgumentException

      Read the number of bytes requested from the stream into a newly created byte buffer.

      Parameters:
        `noOfBytes` - Number of bytes to read.
      Returns:
        Byte buffer containing the requested number of bytes read from the stream.
      Throws:
        `EndOfDataException` - Attempt to read beyond the limit set for the stream.
        `IOException` - An IO problem occurred when trying to read from the stream.
        `IllegalArgumentException` - Cannot read a negative number of bytes.
      See Also:
        `write(ByteBuffer)`, `getLimit()`, `getPosition()`

    - #### write

          int write(ByteBuffer buffer)
             throws EndOfDataException,
                    IOException

      Write the number of bytes requested to the stream from the given byte buffer.

      Parameters:
        `buffer` - Buffer of data to write. Data is written from the current position to the limit set for the given buffer.
      Returns:
        Number of bytes actually written.
      Throws:
        `EndOfDataException` - Attempt to write beyond the limit set for the stream.
        `IOException` - An IO problem occurred when trying to write to the stream.
      See Also:
        `read(int)`, `getPosition()`, `getLimit()`

    - #### close

          void close()

      Close the stream and release any associated systems resources.

    - #### getByteOrder

          ByteOrder getByteOrder()

      Returns the byte order of the stream.

      Returns:
        Byte order of the stream.

    - #### getStreamURI

          URI getStreamURI()

      Returns the URI that specifies the location of this stream. The URI can be used to resolve the stream and includes just enough information that the stream can be opened and read or written. For example, an AAF stream contains the structured storage path within the file where the stream can be accessed, whereas an MXF stream contains the body and index stream identifiers.

      Returns:
        URI that specifies the location of the stream.
      See Also:
        `StreamResolver`

    - #### clone

          Stream clone()

      Create a cloned copy of the underlying stream accessor class.

      Returns:
        Cloned copy of the underlying stream accessor class.

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