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

tv.amwa.maj.meta.impl

## Class TypeDefinitionStreamImpl

- java.lang.Object
- - tv.amwa.maj.meta.impl.MetaDefinitionImpl
  - - tv.amwa.maj.meta.impl.TypeDefinitionImpl
    - - tv.amwa.maj.meta.impl.SingletonTypeDefinitionImpl
      - - tv.amwa.maj.meta.impl.TypeDefinitionStreamImpl

- All Implemented Interfaces:
    Serializable, Cloneable, CommonConstants, MetadataObject, WeakReferenceTarget, MetaDefinition, TypeDefinition, TypeDefinitionStream, DefinitionType

      @MediaClass(uuid1=218169601,
                  uuid2=524,
                  uuid3=0,
                  uuid4={6,14,43,52,2,6,1,1},
                  definedName="TypeDefinitionStream",
                  description="The TypeDefinitionStream class defines a property type that is stored in a stream and has a value that consists of a varying number of the bytes.",
                  symbol="TypeDefinitionStream")
      public final class TypeDefinitionStreamImpl
      extends SingletonTypeDefinitionImpl
      implements TypeDefinitionStream, Serializable, Cloneable

  Implements the definition of a property type that is stored in a stream and has a value that consists of a varying number of the bytes.

  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TypeDefinitionStreamImpl.StreamValue`

    - ### Nested classes/interfaces inherited from class tv.amwa.maj.meta.impl.SingletonTypeDefinitionImpl

      `SingletonTypeDefinitionImpl.SingletonMethodBag`

    - ### Nested classes/interfaces inherited from class tv.amwa.maj.meta.impl.TypeDefinitionImpl

      `TypeDefinitionImpl.PropertyValueImpl`

  - ### Field Summary

    - ### Fields inherited from interface tv.amwa.maj.constant.CommonConstants

      `AAF_METADICT_NAMESPACE, AAF_METADICT_PREFIX, AAF_XML_NAMESPACE, AAF_XML_PREFIX, ApplicationPluginObjectID, ApplicationPluginsID, MAX_NUM_RGBA_COMPS, MemberOfID, ObjectClassID, ParentClassID, PropertiesID, XMLClassIDAsAttributeName`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TypeDefinitionStreamImpl(AUID identification, String typeName)` Creates and initializes a new type definition for a streams, which defines a property type that is stored in a stream and has a value that consists of a varying number of the bytes.

  - ### Method Summary

    All Methods Instance Methods Concrete 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` | `appendMetadictXML(Node metadict, String namespace, String prefix)` Append an XML representation of this meta definition to the given XML node.
    `void` | `clearStoredByteOrder(PropertyValue streamProperty)` Clear the stored byte order of the given stream property value.
    `TypeDefinitionStream` | `clone()` Create a cloned copy of this meta definition.
    `PropertyValue` | `createFromBytes(ByteBuffer buffer)` Create a value of this type by reading the bytes in the given byte buffer.
    `PropertyValue` | `createValue(Object javaValue)` Create a property value from the given Java object.
    `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.
    `TypeCategory` | `getTypeCategory()` Returns the type category to which this type definition belongs, which corresponds to its sub interface.
    `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 class tv.amwa.maj.meta.impl.SingletonTypeDefinitionImpl

      `setPropertyValue`

    - ### Methods inherited from class tv.amwa.maj.meta.impl.TypeDefinitionImpl

      `getNamespace, getPrefix, getPropertyValue, initalizeTypeNameMap, lengthAsBytes, nameToAAFName, resolveReferences, writeAsBytes, writeAsStructuredStorageBytes`

    - ### Methods inherited from class tv.amwa.maj.meta.impl.MetaDefinitionImpl

      `aafNameToName, appendXMLChildren, deepEquals, equals, getAAFNamesInUse, getAliases, getAUID, getComment, getDescription, getIdentification, getName, getSymbol, getWeakTargetReference, hashCode, initializeMetaDefinitionIdentification, initializeMetaDefinitionName, setAAFNamesInUse, setAliases, setDescription, setIdentification, setName, setNamespace, setPrefix, setSymbol, toString`

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

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

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

      `getPropertyValue, lengthAsBytes, resolveReferences, setPropertyValue, writeAsBytes, writeAsStructuredStorageBytes`

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

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

- - ### Constructor Detail

    - #### TypeDefinitionStreamImpl

          public TypeDefinitionStreamImpl(AUID identification,
                                          @AAFString
                                          String typeName)
                                   throws NullPointerException

      Creates and initializes a new type definition for a streams, which defines a property type that is stored in a stream and has a value that consists of a varying number of the bytes. The order of the bytes is meaningful.

      Creating new and unregistered type definitions is not recommended as this may cause interoperability issues with other systems. The official registry of type definitions is available from SMPTE at SMPTE Metadata Registries And Related Items. The full range of data types documented in the AAF 1.1 object specification can be accessed by name and identification using either `Warehouse.lookForType(String)` or `Warehouse.lookForType(tv.amwa.maj.record.AUID)` respectively.

      Parameters:
        `identification` - AUID to be used to identify this stream type.
        `typeName` - Friendly name for this type definition.
      Throws:
        `NullPointerException` - The identification argument is `null`.

  - ### Method Detail

    - #### append

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

      Description copied from interface: `TypeDefinitionStream`

      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.

      Specified by:
        `append` in interface `TypeDefinitionStream`
      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.

    - #### appendElements

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

      Description copied from interface: `TypeDefinitionStream`

      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.

      Specified by:
        `appendElements` in interface `TypeDefinitionStream`
      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.

    - #### clearStoredByteOrder

          public void clearStoredByteOrder(PropertyValue streamProperty)
                                    throws NullPointerException,
                                           IllegalPropertyValueException

      Description copied from interface: `TypeDefinitionStream`

      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.

      Specified by:
        `clearStoredByteOrder` in interface `TypeDefinitionStream`
      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.

    - #### getPosition

          public long getPosition(PropertyValue streamProperty)
                           throws NullPointerException,
                                  IllegalPropertyValueException,
                                  IOException

      Description copied from interface: `TypeDefinitionStream`

      Returns the current position within the given stream property value.

      Specified by:
        `getPosition` in interface `TypeDefinitionStream`
      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.

    - #### getSize

          public long getSize(PropertyValue streamProperty)
                       throws NullPointerException,
                              IllegalPropertyValueException,
                              IOException

      Description copied from interface: `TypeDefinitionStream`

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

      Specified by:
        `getSize` in interface `TypeDefinitionStream`
      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.

    - #### getStoredByteOrder

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

      Description copied from interface: `TypeDefinitionStream`

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

      Specified by:
        `getStoredByteOrder` in interface `TypeDefinitionStream`
      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:
        `TypeDefinitionStream.hasStoredByteOrder(PropertyValue)`

    - #### hasStoredByteOrder

          public boolean hasStoredByteOrder(PropertyValue streamProperty)
                                     throws NullPointerException,
                                            IllegalPropertyValueException

      Description copied from interface: `TypeDefinitionStream`

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

      Specified by:
        `hasStoredByteOrder` in interface `TypeDefinitionStream`
      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:
        `TypeDefinitionStream.getStoredByteOrder(PropertyValue)`

    - #### read

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

      Description copied from interface: `TypeDefinitionStream`

      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.

      Specified by:
        `read` in interface `TypeDefinitionStream`
      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.
        `EndOfDataException` - Cannot read the requested amount of data as not enough bytes remain in the given stream property value at its current position.
        `IllegalPropertyValueException` - The given property value is not defined by this stream type definition.
        `IOException` - Error occurred when trying to access the underlying stream.

    - #### readElements

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

      Description copied from interface: `TypeDefinitionStream`

      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 `TypeDefinitionStream.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.

      Specified by:
        `readElements` in interface `TypeDefinitionStream`
      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:
        `TypeDefinitionStream.writeElements(PropertyValue, TypeDefinition, PropertyValue[])`

    - #### setPosition

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

      Description copied from interface: `TypeDefinitionStream`

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

      Specified by:
        `setPosition` in interface `TypeDefinitionStream`
      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.

    - #### setSize

          public void setSize(PropertyValue streamProperty,
                              long newSize)
                       throws NullPointerException,
                              IllegalArgumentException,
                              IllegalPropertyValueException

      Description copied from interface: `TypeDefinitionStream`

      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 `TypeDefinitionStream.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.

      Specified by:
        `setSize` in interface `TypeDefinitionStream`
      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.
        `IllegalArgumentException`

    - #### setStoredByteOrder

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

      Description copied from interface: `TypeDefinitionStream`

      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.

      Specified by:
        `setStoredByteOrder` in interface `TypeDefinitionStream`
      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.

    - #### write

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

      Description copied from interface: `TypeDefinitionStream`

      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.

      Specified by:
        `write` in interface `TypeDefinitionStream`
      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.

    - #### writeElements

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

      Description copied from interface: `TypeDefinitionStream`

      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.

      Specified by:
        `writeElements` in interface `TypeDefinitionStream`
      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:
        `TypeDefinitionStream.readElements(PropertyValue, TypeDefinition, int)`

    - #### createValue

          public PropertyValue createValue(Object javaValue)
                                    throws ClassCastException

      Description copied from class: `TypeDefinitionImpl`

      Create a property value from the given Java object. If the type of the object is not compatible with this type definition, a `ClassCastException` is thrown.

      Specified by:
        `createValue` in interface `TypeDefinition`
      Specified by:
        `createValue` in class `TypeDefinitionImpl`
      Parameters:
        `javaValue` - Java object to use to create a property value of this type.
      Returns:
        Property value representing the given value.
      Throws:
        `ClassCastException` - The given object cannot be cast to a property value with this type definition.

    - #### getTypeCategory

          public TypeCategory getTypeCategory()

      Description copied from interface: `TypeDefinition`

      Returns the type category to which this type definition belongs, which corresponds to its sub interface. For example, TypeCategory.Int is returned for a `TypeDefinitionInteger`.

      Specified by:
        `getTypeCategory` in interface `TypeDefinition`
      Specified by:
        `getTypeCategory` in class `TypeDefinitionImpl`
      Returns:
        Type category to which the type definition belongs.
      See Also:
        `TypeCategory`

    - #### createFromBytes

          public PropertyValue createFromBytes(ByteBuffer buffer)

      Description copied from interface: `TypeDefinition`

      Create a value of this type by reading the bytes in the given byte buffer. The buffer is assumed to have exactly the number of bytes that represent the value. For example, the length of a string value will be determined by the length (remaining bytes) in the buffer and not by reading a length value from the buffer.

      This method is able to read values written by the `TypeDefinition.writeAsBytes(PropertyValue, ByteBuffer)` method.

      Specified by:
        `createFromBytes` in interface `TypeDefinition`
      Overrides:
        `createFromBytes` in class `TypeDefinitionImpl`
      Parameters:
        `buffer` - Buffer to create a value from.
      Returns:
        Value of this type created from the given byte array.
      See Also:
        `TypeDefinition.writeAsBytes(PropertyValue, ByteBuffer)`, `TypeDefinition.lengthAsBytes(PropertyValue)`

    - #### appendMetadictXML

          public void appendMetadictXML(Node metadict,
                                        String namespace,
                                        String prefix)

      Description copied from interface: `MetaDefinition`

      Append an XML representation of this meta definition to the given XML node.

      Specified by:
        `appendMetadictXML` in interface `MetaDefinition`
      Overrides:
        `appendMetadictXML` in class `MetaDefinitionImpl`
      Parameters:
        `metadict` - Meta dictionary node to append a description of this node to.
      See Also:
        `CommonConstants.AAF_METADICT_NAMESPACE`

    - #### clone

          public TypeDefinitionStream clone()

      Description copied from interface: `MetaDefinition`

      Create a cloned copy of this meta definition.

      Specified by:
        `clone` in interface `MetaDefinition`
      Specified by:
        `clone` in interface `TypeDefinition`
      Specified by:
        `clone` in interface `TypeDefinitionStream`
      Overrides:
        `clone` in class `TypeDefinitionImpl`
      Returns:
        Cloned copy of this meta definition.

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