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

tv.amwa.maj.meta

## Interface TypeDefinitionOpaque

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

      public interface TypeDefinitionOpaque
      extends TypeDefinitionIndirect

  Specifies the definition of property values whose type is specified in each instance, providing access to data opaque to this API and manipulated directly by an application through a handle. The data type of the value may be contained in a key (AUID) that is stored with the data itself. To access the data, its type must be known to the application.

  Note that many of the methods of TypeDefinitionIndirect are overridden by opaque-specific versions in the implementation provided by the MAJ API. In this case, an attempt is made to resolve the type of the opaque data using the assumption that the first 16 bytes represent a key to the data type.

  See Also:
    `TypeCategory.Opaque`, `KLVData`, `KLVDataDefinition`, `TypeDefinitions.Opaque`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `TypeDefinitionOpaque` | `clone()` Create a cloned copy of this opaque type definition.
    `PropertyValue` | `createValueFromHandle(ByteBuffer initialData)` Creates and returns a new opaque property value from the given block of initial data.
    `AUID` | `getActualTypeID(PropertyValue opaqueProperty)` Returns the type identifier of the actual data within the given opaque property value.
    `ByteBuffer` | `getHandle(PropertyValue opaqueProperty)` Read and return the given opaque property value without having to know its contents.
    `void` | `setHandle(PropertyValue opaqueProperty, ByteBuffer handle)` Sets the value of the given opaque property value to the given unknown data.

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

      `createValueFromActualData, createValueFromActualValue, getActualData, getActualSize, getActualType, getActualValue`

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

    - #### getActualTypeID

          AUID getActualTypeID(PropertyValue opaqueProperty)
                        throws NullPointerException,
                               IllegalPropertyValueException

      Returns the type identifier of the actual data within the given opaque property value. This method assumes that the type identifier is stored in the first 16 bytes of the opaque data.

      Parameters:
        `opaqueProperty` - Property value as defined by this opaque type definition.
      Returns:
        Type identifier of the actual data within the given opaque property value.
      Throws:
        `NullPointerException` - The given opaque property definition is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this opaque type definition.
      See Also:
        `Dictionary.lookupKLVDataDefinition(AUID)`, `TypeDefinitionIndirect.getActualType(PropertyValue)`

    - #### getHandle

          @DataBuffer
          ByteBuffer getHandle(PropertyValue opaqueProperty)
                                    throws NullPointerException,
                                           IllegalPropertyValueException

      Read and return the given opaque property value without having to know its contents. The returned buffer of data can be used later by a call to `setHandle(PropertyValue, ByteBuffer)`.

      Parameters:
        `opaqueProperty` - Property value containing unknown data to be returned.
      Returns:
        Buffer of unknown data as contained within the given opaque property value.
      Throws:
        `NullPointerException` - The given opaque property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this opaque type definition.
      See Also:
        `setHandle(PropertyValue, ByteBuffer)`, `TypeDefinitionIndirect.getActualData(PropertyValue)`, `TypeDefinitionIndirect.getActualValue(PropertyValue)`

    - #### setHandle

          void setHandle(PropertyValue opaqueProperty,
                         @DataBuffer
                         ByteBuffer handle)
                  throws NullPointerException,
                         IllegalArgumentException,
                         IllegalPropertyValueException

      Sets the value of the given opaque property value to the given unknown data. This data may have previously been retrieved by a call to `getHandle(PropertyValue)`.

      Parameters:
        `opaqueProperty` - Property value to set the unknown data value for.
        `handle` - Data to set as the value of the given opaque property value.
      Throws:
        `NullPointerException` - One or more of the arguments is `null`.
        `IllegalArgumentException` - A handle must contain at least 16 bytes of data.
        `IllegalPropertyValueException` - The given property value is not defined by this opaque type definition.
      See Also:
        `getHandle(PropertyValue)`, `createValueFromHandle(ByteBuffer)`

    - #### createValueFromHandle

          PropertyValue createValueFromHandle(@DataBuffer
                                              ByteBuffer initialData)
                                       throws NullPointerException,
                                              IllegalArgumentException

      Creates and returns a new opaque property value from the given block of initial data.

      Parameters:
        `initialData` - Buffer containing the handle to use.
      Returns:
        Newly created opaque property value containing the given data.
      Throws:
        `NullPointerException` - The given initial data handle is `null`.
        `IllegalArgumentException` - A handle must contain at least 16 bytes of data.
      See Also:
        `setHandle(PropertyValue, ByteBuffer)`, `getHandle(PropertyValue)`, `TypeDefinitionIndirect.createValueFromActualData(TypeDefinition, byte[])`, `TypeDefinitionIndirect.createValueFromActualValue(PropertyValue)`

    - #### clone

          TypeDefinitionOpaque clone()

      Create a cloned copy of this opaque type definition.

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

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