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

tv.amwa.maj.industry

## Class FileStream

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

- All Implemented Interfaces:
    Cloneable, Stream

      public class FileStream
      extends Object
      implements Stream, Cloneable

  Provides access to stream data represented as a locally accessible file. The file is assumed to be external essence that is not wrapped in any way.

  See Also:
    `MemoryResidentStream`, `StreamResolver`, `EssenceData.getEssenceStream()`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `FileStream(URI streamReference)` Create a new file stream by file reference.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `FileStream` | `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.

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

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### FileStream

          public FileStream(URI streamReference)

      Create a new file stream by file reference. If the file exists, it will be available for reading and writing. If the file does not yet exist, it will be created on the first write operation.

      Parameters:
        `streamReference` - Identifier for the stream, which is a URL with a file scheme.

  - ### Method Detail

    - #### close

          public void close()

      Description copied from interface: `Stream`

      Close the stream and release any associated systems resources.

      Specified by:
        `close` in interface `Stream`

    - #### getLength

          public long getLength()
                         throws IOException

      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.
      Throws:
        `IOException` - An IO problem occurred when trying to access the stream.

    - #### getLimit

          public long getLimit()
                        throws IOException

      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.
      Throws:
        `IOException` - An IO problem occurred when trying to access the stream.
      See Also:
        `Stream.setLimit(long)`

    - #### 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)`

    - #### 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`

    - #### read

          public ByteBuffer read(int noOfBytes)
                          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:
        `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:
        `Stream.write(ByteBuffer)`, `Stream.getLimit()`, `Stream.getPosition()`

    - #### 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.

    - #### 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 buffer)
                    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:
        `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:
        `Stream.read(int)`, `Stream.getPosition()`, `Stream.getLimit()`

    - #### 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.

    - #### clone

          public FileStream 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.

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