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

tv.amwa.maj.meta

## Interface TypeDefinitionFixedArray

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

      public interface TypeDefinitionFixedArray
      extends TypeDefinition

  Specifies the definition of a property type that has a fixed number of values of the underlying type. The order of the values is meaningful.

  See Also:
    `TypeCategory.FixedArray`, `TypeDefinitionVariableArray`, `TypeDefinitionSet`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `TypeDefinitionFixedArray` | `clone()` Create a cloned copy of this fixed array type definition.
    `PropertyValue` | `createValueFromArray(Object[] initialData)` Creates and returns a new fixed array property value from the given Java array.
    `PropertyValue` | `createValueFromValues(PropertyValue[] elementValues)` Creates and returns a fixed array property value from the given array of property values.
    `Object[]` | `getArray(PropertyValue arrayProperty)` Returns a Java array created from the elements of the given fixed array property value.
    `int` | `getCount()` Returns the number of elements of an array defined by this fixed array type definition.
    `List<PropertyValue>` | `getElements(PropertyValue arrayProperty)` Returns a list over all the property values of the given fixed array property value.
    `PropertyValue` | `getElementValue(PropertyValue arrayProperty, int index)` Returns the member property value at the given index through the given fixed array property value.
    `TypeDefinition` | `getType()` Returns the underlying type of that defines the type of each element of the array defined by this fixed array type definition.
    `void` | `setArray(PropertyValue arrayProperty, Object[] data)` Sets the value of the given fixed array property value using the given Java array, setting the elements of the fixed array to be values given by the elements of the Java array.
    `void` | `setElementValue(PropertyValue arrayProperty, int index, PropertyValue memberProperty)` Sets the value of a member of the given fixed array property value at the given index using the given 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

    - #### getType

          TypeDefinition getType()

      Returns the underlying type of that defines the type of each element of the array defined by this fixed array type definition.

      Returns:
        Element type property of this fixed array type definition.

    - #### getCount

          @UInt32
          int getCount()

      Returns the number of elements of an array defined by this fixed array type definition.

      Returns:
        Number of elements of an array defined by this fixed array type definition.

    - #### createValueFromValues

          PropertyValue createValueFromValues(PropertyValue[] elementValues)
                                       throws NullPointerException,
                                              BadParameterException,
                                              BadTypeException

      Creates and returns a fixed array property value from the given array of property values.

      Parameters:
        `elementValues` - Property value array to use to initialize the new fixed array property value.
      Returns:
        Newly created fixed array property value with values copied from the given property value array.
      Throws:
        `NullPointerException` - The given array of element values is `null` or one or more of its elements is `null`.
        `BadParameterException` - The given array of property values is of a different size to that required by the fixed array type definition, as returned by `getCount()`.
        `BadTypeException` - One or more of the elements of the given property value array cannot be converted to values of the underlying type of the fixed type array definition, as returned by `getType()`.

    - #### createValueFromArray

          PropertyValue createValueFromArray(Object[] initialData)
                                      throws NullPointerException,
                                             BadParameterException,
                                             BadTypeException

      Creates and returns a new fixed array property value from the given Java array. The elements of the Java array are converted to property values of the underlying type of the fixed array type definition, as returned by `getType()` and using a call to `TypeDefinition.createValue(Object)`.

      Parameters:
        `initialData` - Java array of data to use to initialize the new fixed array property value.
      Returns:
        Newly created fixed array property value with values converted from the given Java array.
      Throws:
        `NullPointerException` - The argument is `null`, or one or more of the elements of the given Java array are `null`.
        `BadParameterException` - The given Java array is of a different size to that required by the fixed array type definition, as returned by `getCount()`.
        `BadTypeException` - One or more of the elements of the given Java array cannot be converted to values of the underlying type of the fixed type array definition, as returned by `getType()`.
      See Also:
        `TypeDefinition.createValue(Object)`, `getArray(PropertyValue)`, `setArray(PropertyValue, Object[])`

    - #### getElementValue

          PropertyValue getElementValue(PropertyValue arrayProperty,
                                        @UInt32
                                        int index)
                                 throws NullPointerException,
                                        IndexOutOfBoundsException,
                                        IllegalPropertyValueException

      Returns the member property value at the given index through the given fixed array property value.

      Parameters:
        `arrayProperty` - Fixed array property value to retrieve a a member property value from.
        `index` - 0-based index into the given fixed array property value to use to locate the required member property value.
      Returns:
        Member property value at the given index in the given fixed array property value.
      Throws:
        `NullPointerException` - The given fixed array property value is `null`.
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for an array defined by this fixed array type definition.
        `IllegalPropertyValueException` - The fixed array property value is not defined by this fixed array type definition.

    - #### getArray

          Object[] getArray(PropertyValue arrayProperty)
                     throws NullPointerException,
                            IllegalPropertyValueException

      Returns a Java array created from the elements of the given fixed array property value. The array is created with a call to `PropertyValue.getValue()` on each of the members of the given array.

      Parameters:
        `arrayProperty` - Fixed array property value to create a fixed array property value from.
      Returns:
        Java array containing elements with values matching the values of the elements of the given fixed array property value.
      Throws:
        `NullPointerException` - Argument is null.
        `IllegalPropertyValueException` - The fixed array property value is not defined by the fixed array type definition.
      See Also:
        `createValueFromArray(Object[])`, `getElements(PropertyValue)`

    - #### setElementValue

          void setElementValue(PropertyValue arrayProperty,
                               @UInt32
                               int index,
                               PropertyValue memberProperty)
                        throws NullPointerException,
                               IllegalPropertyValueException,
                               IndexOutOfBoundsException,
                               BadTypeException

      Sets the value of a member of the given fixed array property value at the given index using the given value.

      Parameters:
        `arrayProperty` - Fixed array property value for which a member is to be set.
        `index` - 0-based index of the member value to change.
        `memberProperty` - Replacement value for the member of the given array at the given index.
      Throws:
        `NullPointerException` - One or both of the array and/or member property values is/are `null`.
        `IllegalPropertyValueException` - The fixed array property value is not defined by this fixed array type definition.
        `IndexOutOfBoundsException` - The index is outside the acceptable range for arrays of this fixed array type definition.
        `BadTypeException` - The given member property definition is not compatible with the underlying type of the fixed array type definition, as returned by `getType()`.
      See Also:
        `getElements(PropertyValue)`

    - #### setArray

          void setArray(PropertyValue arrayProperty,
                        Object[] data)
                 throws NullPointerException,
                        IllegalPropertyValueException,
                        BadParameterException,
                        BadTypeException

      Sets the value of the given fixed array property value using the given Java array, setting the elements of the fixed array to be values given by the elements of the Java array. Both arrays must the same length and it must be possible to convert the values of the Java array to the underlying type of the fixed array type definition, as returned by `getType()` and using `TypeDefinition.createValue(Object)`.

      Parameters:
        `arrayProperty` - Fixed array property value to have the value of all of its elements set.
        `data` - Java array containing elements to be used to set the values of the elements of the given fixed array property value.
      Throws:
        `NullPointerException` - One or more of the arguments is null, or one or more of the elements of the given Java array is null.
        `IllegalPropertyValueException` - The fixed array property value is not defined by the fixed array type definition.
        `BadParameterException` - The given Java array is a different size to that defined by the fixed array type definition, as returned by `getCount()`.
        `BadTypeException` - The Java array contains one or more objects that cannot be converted to elements of the underlying type of this fixed array type definition, as returned by `getType()`.
      See Also:
        `createValueFromArray(Object[])`, `TypeDefinition.createValue(Object)`

    - #### getElements

          List<PropertyValue> getElements(PropertyValue arrayProperty)
                                   throws NullPointerException,
                                          IllegalPropertyValueException

      Returns a list over all the property values of the given fixed array property value.

      Parameters:
        `arrayProperty` - Fixed array property value to create a list from.
      Returns:
        List of the member elements of the given fixed array property value.
      Throws:
        `NullPointerException` - The given fixed array property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this fixed array type definition.
      See Also:
        `getArray(PropertyValue)`, `getElementValue(PropertyValue, int)`

    - #### clone

          TypeDefinitionFixedArray clone()

      Create a cloned copy of this fixed array type definition.

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

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