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

tv.amwa.maj.meta

## Interface TypeDefinitionIndirect

- All Superinterfaces:
    MetadataObject, MetaDefinition, TypeDefinition, WeakReferenceTarget
  All Known Subinterfaces:
    TypeDefinitionOpaque
  All Known Implementing Classes:
    TypeDefinitionIndirectImpl, TypeDefinitionOpaqueImpl

      public interface TypeDefinitionIndirect
      extends TypeDefinition

  Specifies the definition of property values whose type is specified in each instance.

  One way to think of property values defined by the indirect property definition is as: a property value with a value that is a property value. One application of a value of indirect type is a tagged value that is used to represent a user comment. Most comments are strings but a comment may take the form of an integer value.

  Note that the MAJ API provides a means to serialize data values to and from byte arrays using Java object serialization. This is an internal mechanism that is exposed to the application through methods such as `getActualData(PropertyValue)`. The binary format created by the MAJ API is not compatible with that of other AAF implementations.

  See Also:
    `TypeCategory.Indirect`, `TaggedValue`, `ConstantValue`, `ControlPoint`, `TypeDefinitions.Indirect`, `PropertyValue`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `TypeDefinitionIndirect` | `clone()` Create a cloned copy of this indirect type definition.
    `PropertyValue` | `createValueFromActualData(TypeDefinition actualType, byte[] initialData)` Creates and returns an indirect property value from the given type definition and serialized data.
    `PropertyValue` | `createValueFromActualValue(PropertyValue actualValue)` Creates and returns an indirect property value that contains the given actual property value.
    `byte[]` | `getActualData(PropertyValue indirectProperty)` Returns a copy of the actual data contained in the indirect property value.
    `int` | `getActualSize(PropertyValue indirectProperty)` Returns the size of the data held by the actual property value embedded within the given indirect property value.
    `TypeDefinition` | `getActualType(PropertyValue indirectProperty)` Returns the type definition of the property value embedded within the given property value.
    `PropertyValue` | `getActualValue(PropertyValue indirectProperty)` Returns the actual property value embedded within the given indirect property value.

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

    - #### createValueFromActualValue

          PropertyValue createValueFromActualValue(PropertyValue actualValue)
                                            throws NullPointerException,
                                                   NotSerializableException

      Creates and returns an indirect property value that contains the given actual property value.

      Parameters:
        `actualValue` - Actual value to embed into the new indirect property value.
      Returns:
        Newly created indirect property value embedding the given actual property value.
      Throws:
        `NullPointerException` - The given original property value is `null`.
        `NotSerializableException` - For creating opaque type values, the given property value cannot be serialized to a stream of opaque bytes.
      See Also:
        `createValueFromActualData(TypeDefinition, byte[])`, `getActualValue(PropertyValue)`

    - #### createValueFromActualData

          PropertyValue createValueFromActualData(TypeDefinition actualType,
                                                  @DataBuffer
                                                  byte[] initialData)
                                           throws NullPointerException,
                                                  EndOfDataException,
                                                  ClassCastException

      Creates and returns an indirect property value from the given type definition and serialized data.

      Parameters:
        `actualType` - Type of the actual data to embed within the new indirect property value.
        `initialData` - Data to use to create the new indirect property value of the given type.
      Returns:
        New indirect property value created from the given type and data.
      Throws:
        `NullPointerException` - One or more of the arguments is `null`.
        `EndOfDataException` - Insufficient data in the given array.
        `ClassCastException` - The type of the data does not match the given type definition.
      See Also:
        `createValueFromActualValue(PropertyValue)`

    - #### getActualValue

          PropertyValue getActualValue(PropertyValue indirectProperty)
                                throws NullPointerException,
                                       IllegalPropertyValueException,
                                       TypeNotFoundException

      Returns the actual property value embedded within the given indirect property value.

      Parameters:
        `indirectProperty` - Property value containing the embedded actual value to return.
      Returns:
        Actual value from within the given indirect property value.
      Throws:
        `NullPointerException` - The given indirect property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by an indirect type definition.
        `TypeNotFoundException` - For opaque properties, the type attached to the value cannot be resolved.

    - #### getActualSize

          @UInt32
          int getActualSize(PropertyValue indirectProperty)
                             throws NullPointerException,
                                    IllegalPropertyValueException,
                                    IOException

      Returns the size of the data held by the actual property value embedded within the given indirect property value.

      Parameters:
        `indirectProperty` - Property value containing an actual value.
      Returns:
        Size of the data represented by the actual property value.
      Throws:
        `NullPointerException` - The given indirect property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by an indirect type definition.
        `IOException` - An error occurred white trying to write the property's value to a byte array.
      See Also:
        `getActualData(PropertyValue)`

    - #### getActualType

          TypeDefinition getActualType(PropertyValue indirectProperty)
                                throws NullPointerException,
                                       IllegalPropertyValueException,
                                       TypeNotFoundException

      Returns the type definition of the property value embedded within the given property value. This is effectively `getActualValue(PropertyValue)` followed by `PropertyValue.getType()`.

      Parameters:
        `indirectProperty` - Property value containing an actual property value to determine the type of.
      Returns:
        Type definition of the actual property value in the given indirect property value.
      Throws:
        `NullPointerException` - The given indirect property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by an indirect type definition.
        `TypeNotFoundException` - For opaque type definitions, a type matching the values key cannot be found.
      See Also:
        `getActualValue(PropertyValue)`, `PropertyValue.getType()`

    - #### getActualData

          byte[] getActualData(PropertyValue indirectProperty)
                        throws NullPointerException,
                               IllegalPropertyValueException,
                               IOException

      Returns a copy of the actual data contained in the indirect property value.

      Parameters:
        `indirectProperty` - Property value containing an actual value.
      Returns:
        Serialized contents of the actual property value.
      Throws:
        `NullPointerException` - The given indirect property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by an indirect type definition.
        `IOException` - An error occurred white trying to write the property's value to a byte array.

    - #### clone

          TypeDefinitionIndirect clone()

      Create a cloned copy of this indirect type definition.

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

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