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

tv.amwa.maj.meta

## Interface TypeDefinitionStream

- All Superinterfaces:
    MetadataObject, MetaDefinition, TypeDefinition, WeakReferenceTarget
  All Known Implementing Classes:
    TypeDefinitionStreamImpl

      public interface TypeDefinitionStream
      extends TypeDefinition

  Specifies the definition of a property type that is stored in a stream and has a value that consists of a varying number of bytes. The order of the bytes is meaningful.

  Note that all reads and writes advance the current position of a stream.

  See Also:
    `TypeCategory.Stream`, `DataBuffer`, `EssenceData.getEssenceStream()`, `TypeDefinitions.Stream`, `Stream`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `append(PropertyValue streamProperty, byte[] data)` Extend the given stream property value using the data from the given data buffer, an array of bytes.
    `void` | `appendElements(PropertyValue streamProperty, TypeDefinition elementType, PropertyValue[] data)` Append the elements of the given property value array onto the end of the given stream property value.
    `void` | `clearStoredByteOrder(PropertyValue streamProperty)` Clear the stored byte order of the given stream property value.
    `TypeDefinitionStream` | `clone()` Create a cloned copy of this stream type definition.
    `long` | `getPosition(PropertyValue streamProperty)` Returns the current position within the given stream property value.
    `long` | `getSize(PropertyValue streamProperty)` Returns the number of bytes in the given stream property value, or -1 if the stream is `null`.
    `ByteOrder` | `getStoredByteOrder(PropertyValue streamProperty)` Returns the stored byte order of the given stream property value.
    `boolean` | `hasStoredByteOrder(PropertyValue streamProperty)` Returns `true` if the given property value stream has a stored byte order; otherwise `false`.
    `byte[]` | `read(PropertyValue streamProperty, int dataSize)` Copies the data from the current position in the given stream property value into a data buffer, which is of the given size.
    `PropertyValue[]` | `readElements(PropertyValue streamProperty, TypeDefinition elementType, int numElements)` Reads the given number of elements from the given stream property value of the given element type and returns them as an array of property values.
    `void` | `setPosition(PropertyValue streamProperty, long newPosition)` Sets the position of the given stream property value to that of the given value.
    `void` | `setSize(PropertyValue streamProperty, long newSize)` Sets the number of bytes contained in the given stream property value to the given new size.
    `void` | `setStoredByteOrder(PropertyValue streamProperty, ByteOrder byteOrder)` Sets the stored byte order of the given stream property value to the given byte order.
    `void` | `write(PropertyValue streamProperty, byte[] data)` Write the given data buffer, an array of bytes, into the given stream property value and its current position.
    `void` | `writeElements(PropertyValue streamProperty, TypeDefinition elementType, PropertyValue[] data)` Writes the elements of the given array of property values of the given element type into the given stream property value at its current position.

    - ### Methods inherited from interface tv.amwa.maj.meta.TypeDefinition

      `createFromBytes, createValue, getPropertyValue, getTypeCategory, lengthAsBytes, resolveReferences, setPropertyValue, writeAsBytes, writeAsStructuredStorageBytes`

    - ### Methods inherited from interface tv.amwa.maj.meta.MetaDefinition

      `appendMetadictXML, deepEquals, equals, getAAFNamesInUse, getAliases, getAUID, getDescription, getName, getNamespace, getPrefix, getSymbol, hashCode, setAAFNamesInUse, setDescription, setName, setNamespace, setPrefix, setSymbol, toString`

    - ### Methods inherited from interface tv.amwa.maj.industry.WeakReferenceTarget

      `getWeakTargetReference`

- - ### Method Detail

    - #### getSize

          @Int64
          long getSize(PropertyValue streamProperty)
                       throws NullPointerException,
                              IllegalPropertyValueException,
                              IOException

      Returns the number of bytes in the given stream property value, or -1 if the stream is `null`.

      Parameters:
        `streamProperty` - Stream property value containing the stream to determine the length of.
      Returns:
        Number of bytes in the stream of the given stream property value.
      Throws:
        `NullPointerException` - The given stream property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `IOException` - Cannot access the underlying stream to determine the size.

    - #### setSize

          void setSize(PropertyValue streamProperty,
                       @Int64
                       long newSize)
                throws NullPointerException,
                       IllegalPropertyValueException

      Sets the number of bytes contained in the given stream property value to the given new size. If the new size is smaller than the current size, as returned by `getSize(PropertyValue)`, then the data will be truncated. If the size is larger, the beginning section of the stream value will be the same as the existing stream.

      Parameters:
        `streamProperty` - Stream property value that is to have a new size.
        `newSize` - New size, measured in bytes, for the given stream property value.
      Throws:
        `NullPointerException` - The given stream property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.

    - #### getPosition

          @Int64
          long getPosition(PropertyValue streamProperty)
                           throws NullPointerException,
                                  IllegalPropertyValueException,
                                  IOException

      Returns the current position within the given stream property value.

      Parameters:
        `streamProperty` - Stream property value to find the current position of.
      Returns:
        Current position in the given stream property value.
      Throws:
        `NullPointerException` - The given stream property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `IOException` - Error occurred when trying to access the underlying stream.

    - #### setPosition

          void setPosition(PropertyValue streamProperty,
                           @Int64
                           long newPosition)
                    throws NullPointerException,
                           IllegalPropertyValueException,
                           IllegalArgumentException,
                           IOException

      Sets the position of the given stream property value to that of the given value.

      Parameters:
        `streamProperty` - Stream property value to have its position set.
        `newPosition` - New position to set for the given stream property value.
      Throws:
        `NullPointerException` - The given stream property value is `null`.
        `IllegalArgumentException` - The given position is outside the acceptable range for the given stream property.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `IOException` - Error occurred when trying to access the underlying stream.

    - #### read

          @DataBuffer
          byte[] read(PropertyValue streamProperty,
                                  @UInt32
                                  int dataSize)
                           throws NullPointerException,
                                  IllegalArgumentException,
                                  IllegalPropertyValueException,
                                  EndOfDataException,
                                  IOException

      Copies the data from the current position in the given stream property value into a data buffer, which is of the given size. The data buffer is a byte array that is returned by the method.

      Parameters:
        `streamProperty` - Stream property array to copy data from.
        `dataSize` - Size of the data buffer to create and return.
      Returns:
        Data buffer containing data copied from the given stream property at its current position and of the given size.
      Throws:
        `NullPointerException` - The given stream property value is `null`.
        `IllegalArgumentException` - Cannot read a negative number of bytes from a stream property value.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `EndOfDataException` - Cannot read the requested amount of data as not enough bytes remain in the given stream property value at its current position.
        `IOException` - Error occurred when trying to access the underlying stream.

    - #### write

          void write(PropertyValue streamProperty,
                     byte[] data)
              throws NullPointerException,
                     IllegalPropertyValueException,
                     EndOfDataException,
                     IOException

      Write the given data buffer, an array of bytes, into the given stream property value and its current position. The number of bytes written is the same as the size of the given data buffer.

      Parameters:
        `streamProperty` - Stream property value to have data written into at its current position.
        `data` - Data to write into the given stream property value at its current position.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `EndOfDataException` - The write operation will exceed the current size of the stream.
        `IOException` - Error occurred when trying to access the underlying stream.

    - #### append

          void append(PropertyValue streamProperty,
                      byte[] data)
               throws NullPointerException,
                      IllegalPropertyValueException,
                      DataSizeException

      Extend the given stream property value using the data from the given data buffer, an array of bytes. The size of the stream will increase by the size of the given data buffer.

      Parameters:
        `streamProperty` - Stream property value to extend the given data buffer.
        `data` - Data buffer to use to extend the given stream property value.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `DataSizeException` - Not enough space was available to extend the given stream property value by the given number of bytes.

    - #### hasStoredByteOrder

          @Bool
          boolean hasStoredByteOrder(PropertyValue streamProperty)
                                    throws NullPointerException,
                                           IllegalPropertyValueException

      Returns `true` if the given property value stream has a stored byte order; otherwise `false`.

      Parameters:
        `streamProperty` - Stream property value to test.
      Returns:
        Does the given stream property value have as stored property value?
      Throws:
        `NullPointerException` - The given stream property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
      See Also:
        `getStoredByteOrder(PropertyValue)`

    - #### getStoredByteOrder

          ByteOrder getStoredByteOrder(PropertyValue streamProperty)
                                throws NullPointerException,
                                       IllegalPropertyValueException,
                                       PropertyNotPresentException

      Returns the stored byte order of the given stream property value.

      Parameters:
        `streamProperty` - Stream property value to find the byte order for.
      Returns:
        Byte order for the given stream property value.
      Throws:
        `NullPointerException` - The given stream proeprty value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `PropertyNotPresentException` - The byte order is not stored in the given property value.
      See Also:
        `hasStoredByteOrder(PropertyValue)`

    - #### setStoredByteOrder

          void setStoredByteOrder(PropertyValue streamProperty,
                                  ByteOrder byteOrder)
                           throws NullPointerException,
                                  IllegalPropertyValueException

      Sets the stored byte order of the given stream property value to the given byte order. The stream should be empty before calling this method to avoid a mixture of byte orders within the stream.

      Parameters:
        `streamProperty` - Stream property value to set the stored byte order for.
        `byteOrder` - Byte order to set for the given stream property value.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.

    - #### clearStoredByteOrder

          void clearStoredByteOrder(PropertyValue streamProperty)
                             throws NullPointerException,
                                    IllegalPropertyValueException

      Clear the stored byte order of the given stream property value. The stream should be empty before calling this method to avoid a mixture of byte orders within the stream.

      Parameters:
        `streamProperty` - Stream property value to clear the stored property value of.
      Throws:
        `NullPointerException` - The given stream property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.

    - #### readElements

          PropertyValue[] readElements(PropertyValue streamProperty,
                                       TypeDefinition elementType,
                                       @UInt32
                                       int numElements)
                                throws NullPointerException,
                                       IllegalPropertyValueException,
                                       BadTypeException,
                                       EndOfDataException

      Reads the given number of elements from the given stream property value of the given element type and returns them as an array of property values. The read takes place at the current position for the given stream property value and advances the position by the number of bytes read.

      If the `writeElements(PropertyValue, TypeDefinition, PropertyValue[])` method has been used to write an array of property values to a stream property value at a given position, a read from the same position with this method must create an array containing the same values.

      Parameters:
        `streamProperty` - Stream property value to read elements from.
        `elementType` - Type of elements to read from the given stream property value.
        `numElements` - Number of elements to read from the given stream property value.
      Returns:
        Array of elements read from the given stream property value.
      Throws:
        `NullPointerException` - One or both of the stream property or element type arguments is/are `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `BadTypeException` - The values in the data stream do not match the given element type.
        `EndOfDataException` - Reading the number of requested elements will result in a read beyond the end of the given stream property value.
      See Also:
        `writeElements(PropertyValue, TypeDefinition, PropertyValue[])`

    - #### writeElements

          void writeElements(PropertyValue streamProperty,
                             TypeDefinition elementType,
                             PropertyValue[] data)
                      throws NullPointerException,
                             IllegalPropertyValueException,
                             BadTypeException,
                             EndOfDataException

      Writes the elements of the given array of property values of the given element type into the given stream property value at its current position.

      Parameters:
        `streamProperty` - Stream property value into which elements are to be written.
        `elementType` - Type of elements to be written to the given stream property value.
        `data` - Elements to write to the given stream property value at its current position.
      Throws:
        `NullPointerException` - One or more of the arguments is `null`, or one or more of the data elements is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `BadTypeException` - One or more of the elements of the data array are not defined by the given element type.
        `EndOfDataException` - The end of the stream has been reached before all data values could be written. The stream is returned to its previous state.
      See Also:
        `readElements(PropertyValue, TypeDefinition, int)`

    - #### appendElements

          void appendElements(PropertyValue streamProperty,
                              TypeDefinition elementType,
                              PropertyValue[] data)
                       throws NullPointerException,
                              IllegalPropertyValueException,
                              BadTypeException,
                              DataSizeException

      Append the elements of the given property value array onto the end of the given stream property value. All the elements of the given property value array must by of the given type.

      Parameters:
        `streamProperty` - Stream property value to append elements to the end of.
        `elementType` - Type of the elements of data to append.
        `data` - Property values of the elements to append onto the given stream property value.
      Throws:
        `NullPointerException` - One or more of the arguments is `null`, or one or more of the given data values in `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `BadTypeException` - One or more of the elements of the data array are not defined by the given element type.
        `DataSizeException` - The operation failed because not enough space was available to extend the stream.

    - #### clone

          TypeDefinitionStream clone()

      Create a cloned copy of this stream type definition.

      Specified by:
        `clone` in interface `MetaDefinition`
      Specified by:
        `clone` in interface `TypeDefinition`
      Returns:
        Cloned copy of this stream type definition.

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