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

tv.amwa.maj.industry

## Class MemoryResidentStream

- java.lang.Object
- - tv.amwa.maj.industry.MemoryResidentStream

- All Implemented Interfaces:
    Cloneable, Stream

      public class MemoryResidentStream
      extends Object
      implements Stream, Cloneable

  Implementation of a stream as memory-resident byte buffer.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `MemoryResidentStream(ByteBuffer existingBuffer)`
    `MemoryResidentStream(int capacity)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `MemoryResidentStream` | `clone()` Create a cloned copy of the underlying stream accessor class.
    `void` | `close()` Close the stream and release any associated systems resources.
    `boolean` | `equals(Object o)`
    `void` | `finalize()`
    `static void` | `generateStreamORM(Node parent, String namespace, String prefix)`
    `ByteOrder` | `getByteOrder()` Returns the byte order of the stream.
    `int` | `getCapacity()`
    `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` | `getPersistentID()`
    `long` | `getPosition()` Returns the current position for reading from or writing to the stream.
    `long` | `getStart()`
    `URI` | `getStreamURI()` Returns the URI that specifies the location of this stream.
    `int` | `hashCode()`
    `ByteBuffer` | `read(int bytes)` Read the number of bytes requested from the stream into a newly created byte buffer.
    `void` | `setByteOrder(ByteOrder byteOrder)`
    `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 bytes)` Write the number of bytes requested to the stream from the given byte buffer.

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

      `getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### MemoryResidentStream

          public MemoryResidentStream(int capacity)
                               throws IllegalArgumentException

      Throws:
        `IllegalArgumentException`

    - #### MemoryResidentStream

          public MemoryResidentStream(ByteBuffer existingBuffer)
                               throws NullPointerException

      Throws:
        `NullPointerException`

  - ### Method Detail

    - #### read

          public ByteBuffer read(int bytes)
                          throws EndOfDataException,
                                 IOException,
                                 IllegalArgumentException

      Description copied from interface: `Stream`

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

      Specified by:
        `read` in interface `Stream`
      Parameters:
        `bytes` - 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:
        `Stream.write(ByteBuffer)`, `Stream.getLimit()`, `Stream.getPosition()`

    - #### getPosition

          public long getPosition()
                           throws IOException

      Description copied from interface: `Stream`

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

      Specified by:
        `getPosition` in interface `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:
        `Stream.setPosition(long)`

    - #### setPosition

          public void setPosition(long position)
                           throws IllegalArgumentException,
                                  IOException

      Description copied from interface: `Stream`

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

      Specified by:
        `setPosition` in interface `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:
        `Stream.getPosition()`, `Stream.getLimit()`

    - #### write

          public int write(ByteBuffer bytes)
                    throws EndOfDataException,
                           IOException

      Description copied from interface: `Stream`

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

      Specified by:
        `write` in interface `Stream`
      Parameters:
        `bytes` - 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:
        `Stream.read(int)`, `Stream.getPosition()`, `Stream.getLimit()`

    - #### getStart

          public long getStart()

    - #### getLimit

          public long getLimit()

      Description copied from interface: `Stream`

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

      Specified by:
        `getLimit` in interface `Stream`
      Returns:
        Limit position beyond which content cannot be read or written.
      See Also:
        `Stream.setLimit(long)`

    - #### getLength

          public long getLength()

      Description copied from interface: `Stream`

      Returns the length of the stream, measured in bytes.

      Specified by:
        `getLength` in interface `Stream`
      Returns:
        Length of the stream, measured in bytes.

    - #### getPersistentID

          public long getPersistentID()

    - #### close

          public void close()

      Description copied from interface: `Stream`

      Close the stream and release any associated systems resources.

      Specified by:
        `close` in interface `Stream`

    - #### finalize

          public void finalize()

      Overrides:
        `finalize` in class `Object`

    - #### clone

          public MemoryResidentStream clone()

      Description copied from interface: `Stream`

      Create a cloned copy of the underlying stream accessor class.

      Specified by:
        `clone` in interface `Stream`
      Overrides:
        `clone` in class `Object`
      Returns:
        Cloned copy of the underlying stream accessor class.

    - #### setLimit

          public void setLimit(long limit)
                        throws IllegalArgumentException

      Description copied from interface: `Stream`

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

      Specified by:
        `setLimit` in interface `Stream`
      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.

    - #### getCapacity

          public int getCapacity()

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### generateStreamORM

          public static final void generateStreamORM(Node parent,
                                                     String namespace,
                                                     String prefix)

    - #### getStreamURI

          public URI getStreamURI()

      Description copied from interface: `Stream`

      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.

      Specified by:
        `getStreamURI` in interface `Stream`
      Returns:
        URI that specifies the location of the stream.
      See Also:
        `StreamResolver`

    - #### getByteOrder

          public ByteOrder getByteOrder()

      Description copied from interface: `Stream`

      Returns the byte order of the stream.

      Specified by:
        `getByteOrder` in interface `Stream`
      Returns:
        Byte order of the stream.

    - #### setByteOrder

          public void setByteOrder(ByteOrder byteOrder)

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