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

tv.amwa.maj.meta.impl

## Class TypeDefinitionOpaqueImpl

- 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.TypeDefinitionIndirectImpl
        - - tv.amwa.maj.meta.impl.TypeDefinitionOpaqueImpl

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

      @MediaClass(uuid1=218169601,
                  uuid2=546,
                  uuid3=0,
                  uuid4={6,14,43,52,2,6,1,1},
                  definedName="TypeDefinitionOpaque",
                  description="The TypeDefinitionOpaque class defines a property type that has a value whose type is specified in each instance.",
                  symbol="TypeDefinitionOpaque")
      public final class TypeDefinitionOpaqueImpl
      extends TypeDefinitionIndirectImpl
      implements TypeDefinitionOpaque, Serializable, Cloneable

  Implements the definition of a property type that has a value whose type is specified in each instance.

  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TypeDefinitionOpaqueImpl.OpaqueValue`

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

      `TypeDefinitionIndirectImpl.IndirectValue`

    - ### 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
    `TypeDefinitionOpaqueImpl(AUID identification, String typeName)` Creates and initializes a new opaque type definition, which defines a property type that has a value whose type is specified in each instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendMetadictXML(Node metadict, String namespace, String prefix)` Append an XML representation of this meta definition to the given XML node.
    `TypeDefinitionOpaque` | `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.
    `PropertyValue` | `createValueFromActualData(AUID actualTypeId, byte[] initData)`
    `PropertyValue` | `createValueFromActualData(AUID actualTypeId, byte[] initData, ByteOrder byteOrder)`
    `PropertyValue` | `createValueFromActualData(TypeDefinition type, byte[] initData)` Creates and returns an indirect property value from the given type definition and serialized data.
    `PropertyValue` | `createValueFromActualValue(PropertyValue propertyValue)` Creates and returns an indirect property value that contains the given actual property value.
    `PropertyValue` | `createValueFromHandle(ByteBuffer initData)` Creates and returns a new opaque property value from the given block of initial data.
    `byte[]` | `getActualData(PropertyValue opaqueProperty)` Returns a copy of the actual data contained in the indirect property value.
    `int` | `getActualSize(PropertyValue opaqueProperty)` Returns the size of the data held by the actual property value embedded within the given indirect property value.
    `TypeDefinition` | `getActualType(PropertyValue opaqueProperty)` Returns the type definition of the property value embedded within the given property value.
    `AUIDImpl` | `getActualTypeID(PropertyValue opaqueProperty)` Returns the type identifier of the actual data within the given opaque property value.
    `PropertyValue` | `getActualValue(PropertyValue opaqueProperty)` Returns the actual property value embedded within the given indirect property value.
    `ByteBuffer` | `getHandle(PropertyValue opaqueProperty)` Read and return the given opaque property value without having to know its contents.
    `TypeCategory` | `getTypeCategory()` Returns the type category to which this type definition belongs, which corresponds to its sub interface.
    `long` | `lengthAsBytes(PropertyValue value)` Returns the number of bytes that the given value of this type is serialized as a sequence of bytes.
    `void` | `setDictionary(MetaDictionary dictionary)`
    `void` | `setHandle(PropertyValue opaqueProperty, ByteBuffer handle)` Sets the value of the given opaque property value to the given unknown data.
    `List<PropertyValue>` | `writeAsBytes(PropertyValue value, ByteBuffer buffer)` Write the given property value of this type to the given byte stream.

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

      `writeAsStructuredStorageBytes`

    - ### 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, nameToAAFName, resolveReferences`

    - ### 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, resolveReferences, setPropertyValue, 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

    - #### TypeDefinitionOpaqueImpl

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

      Creates and initializes a new opaque type definition, which defines a property type that has a value whose type is specified in each instance.

      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 used to identify this type.
        `typeName` - Friendly name for the opaque type definition.
      Throws:
        `NullPointerException` - The identification argument is `null`.

  - ### Method Detail

    - #### createValueFromHandle

          public final PropertyValue createValueFromHandle(ByteBuffer initData)
                                                    throws NullPointerException,
                                                           IllegalArgumentException

      Description copied from interface: `TypeDefinitionOpaque`

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

      Specified by:
        `createValueFromHandle` in interface `TypeDefinitionOpaque`
      Parameters:
        `initData` - 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:
        `TypeDefinitionOpaque.setHandle(PropertyValue, ByteBuffer)`, `TypeDefinitionOpaque.getHandle(PropertyValue)`, `TypeDefinitionIndirect.createValueFromActualData(TypeDefinition, byte[])`, `TypeDefinitionIndirect.createValueFromActualValue(PropertyValue)`

    - #### getActualTypeID

          public final AUIDImpl getActualTypeID(PropertyValue opaqueProperty)
                                         throws NullPointerException,
                                                IllegalPropertyValueException

      Description copied from interface: `TypeDefinitionOpaque`

      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.

      Specified by:
        `getActualTypeID` in interface `TypeDefinitionOpaque`
      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

          public final ByteBuffer getHandle(PropertyValue opaqueProperty)
                                     throws NullPointerException,
                                            IllegalPropertyValueException

      Description copied from interface: `TypeDefinitionOpaque`

      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 `TypeDefinitionOpaque.setHandle(PropertyValue, ByteBuffer)`.

      Specified by:
        `getHandle` in interface `TypeDefinitionOpaque`
      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:
        `TypeDefinitionOpaque.setHandle(PropertyValue, ByteBuffer)`, `TypeDefinitionIndirect.getActualData(PropertyValue)`, `TypeDefinitionIndirect.getActualValue(PropertyValue)`

    - #### setHandle

          public final void setHandle(PropertyValue opaqueProperty,
                                      ByteBuffer handle)
                               throws NullPointerException,
                                      IllegalPropertyValueException,
                                      IllegalArgumentException

      Description copied from interface: `TypeDefinitionOpaque`

      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 `TypeDefinitionOpaque.getHandle(PropertyValue)`.

      Specified by:
        `setHandle` in interface `TypeDefinitionOpaque`
      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`.
        `IllegalPropertyValueException` - The given property value is not defined by this opaque type definition.
        `IllegalArgumentException` - A handle must contain at least 16 bytes of data.
      See Also:
        `TypeDefinitionOpaque.getHandle(PropertyValue)`, `TypeDefinitionOpaque.createValueFromHandle(ByteBuffer)`

    - #### createValueFromActualData

          public final PropertyValue createValueFromActualData(AUID actualTypeId,
                                                               byte[] initData)
                                                        throws NullPointerException

      Throws:
        `NullPointerException`

    - #### createValueFromActualData

          public final PropertyValue createValueFromActualData(AUID actualTypeId,
                                                               byte[] initData,
                                                               ByteOrder byteOrder)
                                                        throws NullPointerException

      Throws:
        `NullPointerException`

    - #### createValueFromActualData

          public final PropertyValue createValueFromActualData(TypeDefinition type,
                                                               byte[] initData)
                                                        throws NullPointerException

      Description copied from interface: `TypeDefinitionIndirect`

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

      Specified by:
        `createValueFromActualData` in interface `TypeDefinitionIndirect`
      Overrides:
        `createValueFromActualData` in class `TypeDefinitionIndirectImpl`
      Parameters:
        `type` - Type of the actual data to embed within the new indirect property value.
        `initData` - 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`.
      See Also:
        `TypeDefinitionIndirect.createValueFromActualData(tv.amwa.maj.meta.TypeDefinition, byte[])`

    - #### getActualData

          public final byte[] getActualData(PropertyValue opaqueProperty)
                                     throws NullPointerException,
                                            IllegalPropertyValueException

      Description copied from interface: `TypeDefinitionIndirect`

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

      Specified by:
        `getActualData` in interface `TypeDefinitionIndirect`
      Overrides:
        `getActualData` in class `TypeDefinitionIndirectImpl`
      Parameters:
        `opaqueProperty` - 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.
      See Also:
        `TypeDefinitionIndirect.getActualData(tv.amwa.maj.industry.PropertyValue)`

    - #### getActualSize

          public final int getActualSize(PropertyValue opaqueProperty)
                                  throws NullPointerException,
                                         IllegalPropertyValueException

      Description copied from interface: `TypeDefinitionIndirect`

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

      Specified by:
        `getActualSize` in interface `TypeDefinitionIndirect`
      Overrides:
        `getActualSize` in class `TypeDefinitionIndirectImpl`
      Parameters:
        `opaqueProperty` - 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.
      See Also:
        `TypeDefinitionIndirect.getActualSize(tv.amwa.maj.industry.PropertyValue)`

    - #### setDictionary

          public final void setDictionary(MetaDictionary dictionary)
                                   throws NullPointerException

      Throws:
        `NullPointerException`

    - #### getActualType

          public final TypeDefinition getActualType(PropertyValue opaqueProperty)
                                             throws NullPointerException,
                                                    IllegalPropertyValueException,
                                                    TypeNotFoundException

      Description copied from interface: `TypeDefinitionIndirect`

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

      Specified by:
        `getActualType` in interface `TypeDefinitionIndirect`
      Overrides:
        `getActualType` in class `TypeDefinitionIndirectImpl`
      Parameters:
        `opaqueProperty` - 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:
        `TypeDefinitionIndirect.getActualType(tv.amwa.maj.industry.PropertyValue)`

    - #### getActualValue

          public final PropertyValue getActualValue(PropertyValue opaqueProperty)
                                             throws NullPointerException,
                                                    IllegalPropertyValueException,
                                                    TypeNotFoundException,
                                                    ClassCastException

      Description copied from interface: `TypeDefinitionIndirect`

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

      Specified by:
        `getActualValue` in interface `TypeDefinitionIndirect`
      Overrides:
        `getActualValue` in class `TypeDefinitionIndirectImpl`
      Parameters:
        `opaqueProperty` - 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.
        `ClassCastException`
      See Also:
        `TypeDefinitionIndirect.getActualValue(tv.amwa.maj.industry.PropertyValue)`

    - #### createValueFromActualValue

          public final PropertyValue createValueFromActualValue(PropertyValue propertyValue)
                                                         throws NullPointerException,
                                                                NotSerializableException

      Description copied from interface: `TypeDefinitionIndirect`

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

      Specified by:
        `createValueFromActualValue` in interface `TypeDefinitionIndirect`
      Overrides:
        `createValueFromActualValue` in class `TypeDefinitionIndirectImpl`
      Parameters:
        `propertyValue` - 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:
        `TypeDefinitionIndirect.createValueFromActualValue(tv.amwa.maj.industry.PropertyValue)`

    - #### createValue

          public final 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`
      Overrides:
        `createValue` in class `TypeDefinitionIndirectImpl`
      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.
      See Also:
        `TypeDefinitionImpl.createValue(java.lang.Object)`

    - #### getTypeCategory

          public final 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`
      Overrides:
        `getTypeCategory` in class `TypeDefinitionIndirectImpl`
      Returns:
        Type category to which the type definition belongs.
      See Also:
        `TypeDefinitionImpl.getTypeCategory()`

    - #### createFromBytes

          public PropertyValue createFromBytes(ByteBuffer buffer)
                                        throws NullPointerException,
                                               EndOfDataException

      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 `TypeDefinitionIndirectImpl`
      Parameters:
        `buffer` - Buffer to create a value from.
      Returns:
        Value of this type created from the given byte array.
      Throws:
        `NullPointerException` - Cannot read values from a `null` buffer.
        `EndOfDataException` - Insufficient bytes remaining in the given buffer to create a value of this type.
      See Also:
        `TypeDefinition.writeAsBytes(PropertyValue, ByteBuffer)`, `TypeDefinition.lengthAsBytes(PropertyValue)`

    - #### writeAsBytes

          public List<PropertyValue> writeAsBytes(PropertyValue value,
                                                  ByteBuffer buffer)
                                           throws NullPointerException,
                                                  IllegalPropertyValueException,
                                                  InsufficientSpaceException

      Description copied from interface: `TypeDefinition`

      Write the given property value of this type to the given byte stream. This version is most appropriate for writing KLV streams (MXF files).

      The format used to serialize the value with be compatible with the `TypeDefinition.createFromBytes(ByteBuffer)` method. The number of bytes written to the byte buffer will be the same as returned by `TypeDefinition.lengthAsBytes(PropertyValue)`.

      Specified by:
        `writeAsBytes` in interface `TypeDefinition`
      Overrides:
        `writeAsBytes` in class `TypeDefinitionIndirectImpl`
      Parameters:
        `value` - Value to write to the given buffer.
        `buffer` - Buffer to write the value to.
      Returns:
        List of any strongly referenced property values referenced from the new structure of bytes. Elements of this list will require separate serialization to the stream if the reference if to be resolved.
      Throws:
        `NullPointerException` - Cannot write from a `null` property value and/or to a `null` value.
        `IllegalPropertyValueException` - The given property value is not of this type.
        `InsufficientSpaceException` - Insufficient space to write the given value into the given buffer.
      See Also:
        `TypeDefinition.writeAsStructuredStorageBytes(PropertyValue, ByteBuffer)`, `TypeDefinition.createFromBytes(ByteBuffer)`, `TypeDefinition.lengthAsBytes(PropertyValue)`

    - #### lengthAsBytes

          public long lengthAsBytes(PropertyValue value)
                             throws NullPointerException,
                                    IllegalPropertyValueException

      Description copied from interface: `TypeDefinition`

      Returns the number of bytes that the given value of this type is serialized as a sequence of bytes.

      The number returned by this method is the same as the number of bytes written to a byte buffer by the `TypeDefinition.writeAsBytes(PropertyValue, ByteBuffer)` method.

      Specified by:
        `lengthAsBytes` in interface `TypeDefinition`
      Overrides:
        `lengthAsBytes` in class `TypeDefinitionIndirectImpl`
      Parameters:
        `value` - Value to find the length of when serialized to bytes.
      Returns:
        Number of bytes used to represent the given value when serialized.
      Throws:
        `NullPointerException` - Cannot compute the serialized length of a `null` value.
        `IllegalPropertyValueException` - The given property value is not of this type.
      See Also:
        `TypeDefinition.writeAsBytes(PropertyValue, ByteBuffer)`, `TypeDefinition.createFromBytes(ByteBuffer)`

    - #### 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 `TypeDefinitionIndirectImpl`
      Parameters:
        `metadict` - Meta dictionary node to append a description of this node to.
      See Also:
        `CommonConstants.AAF_METADICT_NAMESPACE`

    - #### clone

          public TypeDefinitionOpaque 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 `TypeDefinitionIndirect`
      Specified by:
        `clone` in interface `TypeDefinitionOpaque`
      Overrides:
        `clone` in class `TypeDefinitionIndirectImpl`
      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.