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

tv.amwa.maj.meta

## Interface TypeDefinitionVariableArray

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

      public interface TypeDefinitionVariableArray
      extends TypeDefinition

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

  Some examples of the underlying type are as follows:

  - Another type definition, such as:
    - `Int64` values with array type `Int64Array`;
    - `AAFString` values with array type `StringArray`;
    - `ChannelStatusModeType` enumeration values with array type `ChannelStatusModeArray`;
    - `AUID` record values with array type `AUIDArray`.
  - A strong object reference to a subclass of interchange object, with the exception of definition objects, such as:
    - References to components with array type `ComponentStrongReferenceVector`;
    - References to control points with array type `ControlPointStrongReferenceVector`.
    Arrays of this type are known as strong reference vectors. The control point example above is called "StrongReferenceVector of ControlPoint" in the AAF object specification and may also be represented as "StrongReferenceVector<ControlPoint>".
  - A weak object reference to a subclass of definition object or meta definition, such as:
    - References to type definitions with array type `TypeDefinitionWeakObjectReference`;
    - References to operation definitions with array type `OperationDefinitionWeakReference`.
    Arrays of this type are known as weak reference vectors. The operation definition example above is called "WeakReferenceVector of OperationDefinition" in the AAF object specification and may also be represented as "WeakReferenceVector<OperationDefinition>".

  Type names as shown in the examples above can be used to retrieve variable array type definitions with a call to `Warehouse.lookForType(String)`.

  See Also:
    `TypeCategory.VariableArray`, `TypeDefinitionFixedArray`, `TypeDefinitionSet`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendElement(PropertyValue arrayProperty, PropertyValue element)` Append the given element to the end of the given array, which is of a type defined by this variable array type definition.
    `TypeDefinitionVariableArray` | `clone()` Create a cloned copy of this variable array type definition.
    `PropertyValue` | `createEmptyValue()` Creates a property value containing an empty variable size array, which is an array with no elements in it yet.
    `PropertyValue` | `createValueFromArray(Object[] initialData)` Create a property value containing a variable size array from the given array of Java objects.
    `PropertyValue` | `createValueFromList(List<Object> initialData)` Creates a property value containing a variable size array from the given list of Java objects.
    `PropertyValue` | `createValueFromValues(PropertyValue[] elementValues)` Creates a property value containing a variable size array from the given array of property values.
    `Object[]` | `getArray(PropertyValue arrayProperty)` Returns an array of Java objects containing the values of the given array.
    `int` | `getCount(PropertyValue arrayProperty)` Returns the number of elements in the given array, which is of a type defined by this variable size type definition.
    `List<PropertyValue>` | `getElements(PropertyValue arrayProperty)` Returns a copy of the internal list of all the elements in the given array.
    `PropertyValue` | `getElementValue(PropertyValue arrayProperty, int index)` Returns the property value from the given array at the given index.
    `TypeDefinition` | `getType()` Returns the type of elements of this variable size array type definition.
    `void` | `insertElement(PropertyValue arrayProperty, int index, PropertyValue element)` Inserts the value of the given element into the given array property.
    `void` | `prependElement(PropertyValue arrayProperty, PropertyValue element)` Prepends a given element to the beginning of the given array.
    `void` | `removeElement(PropertyValue arrayProperty, int index)` Removes an element from the given array at the given zero-based index.
    `void` | `setArray(PropertyValue arrayProperty, List<Object> data)` Sets the elements of a given array from the given list of Java objects.
    `void` | `setArray(PropertyValue arrayProperty, Object[] data)` Sets the elements of a given array from the given array of Java objects.
    `void` | `setElementAt(PropertyValue arrayProperty, int index, PropertyValue element)` Sets an element of the given array at the given index with the given value, replacing the value that is currently stored.

    - ### 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 type of elements of this variable size array type definition.

      Returns:
        Type of elements of this variable size array type definition.

    - #### getCount

          @UInt32
          int getCount(PropertyValue arrayProperty)
                        throws NullPointerException,
                               IllegalPropertyValueException

      Returns the number of elements in the given array, which is of a type defined by this variable size type definition. This method will return 0 if the array is `null` or empty.

      Parameters:
        `arrayProperty` - Property value containing the array to find the size of.
      Returns:
        Number of elements in the given array.
      Throws:
        `NullPointerException` - The given array property is `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.

    - #### appendElement

          void appendElement(PropertyValue arrayProperty,
                             PropertyValue element)
                      throws NullPointerException,
                             IllegalPropertyValueException,
                             BadTypeException

      Append the given element to the end of the given array, which is of a type defined by this variable array type definition.

      Parameters:
        `arrayProperty` - Array to extend with the given element.
        `element` - Element to use to extend the given array.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.
        `BadTypeException` - The given element is not of a type that is compatible with this type of array.
      See Also:
        `prependElement(PropertyValue, PropertyValue)`, `insertElement(PropertyValue, int, PropertyValue)`

    - #### createEmptyValue

          PropertyValue createEmptyValue()

      Creates a property value containing an empty variable size array, which is an array with no elements in it yet.

      Returns:
        Property value containing an empty variable size array.
      See Also:
        `createValueFromArray(Object[])`, `createValueFromList(List)`, `createValueFromValues(PropertyValue[])`

    - #### createValueFromValues

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

      Creates a property value containing a variable size array from the given array of property values.

      Parameters:
        `elementValues` - Array of property values to use to create a variable size array.
      Returns:
        Property value containing the newly created variable size array.
      Throws:
        `NullPointerException` - The given array of element values is `null` or one or more of its elements is/are `null`.
        `BadTypeException` - One of more of the elements of the given array of property values has a type that is not compatible with this array type.
      See Also:
        `createEmptyValue()`, `createValueFromList(List)`, `createValueFromArray(Object[])`

    - #### createValueFromArray

          PropertyValue createValueFromArray(Object[] initialData)
                                      throws ClassCastException

      Create a property value containing a variable size array from the given array of Java objects. Passing a `null` value to this method will create a variable size array property of this type containing a `null` value, which may be used to indicate that a property is not present.

      Parameters:
        `initialData` - Array of Java objects to use as the initial data for the variable size array.
      Returns:
        Property value containing a variable size array created from the given array of Java objects.
      Throws:
        `ClassCastException` - It is not possible to cast one or more of the given elements of the Java array to the underlying element type of this type definition.
      See Also:
        `createEmptyValue()`, `createValueFromList(List)`, `createValueFromValues(PropertyValue[])`, `setArray(PropertyValue, Object[])`

    - #### createValueFromList

          PropertyValue createValueFromList(List<Object> initialData)
                                     throws ClassCastException

      Creates a property value containing a variable size array from the given list of Java objects. Passing a `null` value to this method will create a variable size array property of this type containing a `null` value, which may be used to indicate that a property is not present.

      Parameters:
        `initialData` - List of Java objects to use as the initial data for the variable size array.
      Returns:
        Property value containing a variable size array created from the given array of Java objects.
      Throws:
        `ClassCastException` - One or more of the elements of the given list does not match the underlying element type of this variable size array type definition.
      See Also:
        `createValueFromArray(Object[])`, `setArray(PropertyValue, List)`

    - #### getElementValue

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

      Returns the property value from the given array at the given index.

      Parameters:
        `arrayProperty` - Property containing an array to return a value from.
        `index` - Index into the given array for the value to return.
      Returns:
        Property value from the given array at the given index.
      Throws:
        `NullPointerException` - The given array property value is `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current size of the given array.
      See Also:
        `getArray(PropertyValue)`, `PropertyValue.getValue()`

    - #### getArray

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

      Returns an array of Java objects containing the values of the given array.

      Parameters:
        `arrayProperty` - Property containing the array to convert to an array of Java objects.
      Returns:
        Array of Java objects created from the values of the given array.
      Throws:
        `NullPointerException` - The given array property value is `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.
      See Also:
        `getElements(PropertyValue)`, `getElementValue(PropertyValue, int)`

    - #### setElementAt

          void setElementAt(PropertyValue arrayProperty,
                            @UInt32
                            int index,
                            PropertyValue element)
                     throws NullPointerException,
                            IllegalPropertyValueException,
                            IndexOutOfBoundsException,
                            BadTypeException

      Sets an element of the given array at the given index with the given value, replacing the value that is currently stored.

      Parameters:
        `arrayProperty` - Property value containing the array to be modified.
        `index` - Index into the given array of the element to be replaced by the given value.
        `element` - Value to set at the given index in the given array.
      Throws:
        `NullPointerException` - The given array property value and/or the given element is/are `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current size of the given array.
        `BadTypeException` - The given element type is not compatible with the element type of this array.
      See Also:
        `insertElement(PropertyValue, int, PropertyValue)`

    - #### setArray

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

      Sets the elements of a given array from the given array of Java objects. The type definition returned by `getType()` must be able to transform each of the objects in the given Java array into the appropriate type, otherwise a `IllegalPropertyValueException` will be thrown.

      Parameters:
        `arrayProperty` - Property containing the array to have its data set.
        `data` - List of Java objects to set as the elements of the given array.
      Throws:
        `NullPointerException` - The given array property argument is `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.
        `ClassCastException` - It is not possible to cast one or more of the given Java objects to a type compatible with this type definition.
      See Also:
        `TypeDefinition.createValue(Object)`, `setArray(PropertyValue, List)`

    - #### setArray

          void setArray(PropertyValue arrayProperty,
                        List<Object> data)
                 throws NullPointerException,
                        IllegalPropertyValueException,
                        ClassCastException

      Sets the elements of a given array from the given list of Java objects. The type definition returned by `getType()` must be able to transform each of the objects in the given Java array into the appropriate type, otherwise a `IllegalPropertyValueException` will be thrown.

      Parameters:
        `arrayProperty` - Property containing the array to have its data set.
        `data` - Array of Java objects to set as the elements of the given array.
      Throws:
        `NullPointerException` - The given array property value is `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.
        `ClassCastException` - It is not possible to cast one or more of the given Java objects to a type compatible with this type definition.
      See Also:
        `TypeDefinition.createValue(Object)`, `setArray(PropertyValue, Object[])`

    - #### getElements

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

      Returns a copy of the internal list of all the elements in the given array.

      Parameters:
        `arrayProperty` - Property containing the array to create an iterator for.
      Returns:
        List containing the elements of the given variable size array.
      Throws:
        `NullPointerException` - The given array property value is `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.
      See Also:
        `getArray(PropertyValue)`

    - #### prependElement

          void prependElement(PropertyValue arrayProperty,
                              PropertyValue element)
                       throws NullPointerException,
                              IllegalPropertyValueException,
                              BadTypeException

      Prepends a given element to the beginning of the given array.

      Parameters:
        `arrayProperty` - Property value of the array to be extended.
        `element` - Element to add to the beginning of the given array.
      Throws:
        `NullPointerException` - The given array property value and/or the given element value is/are `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.
        `BadTypeException` - The given element is not of the correct type to be inserted into this array.
      See Also:
        `appendElement(PropertyValue, PropertyValue)`, `insertElement(PropertyValue, int, PropertyValue)`

    - #### removeElement

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

      Removes an element from the given array at the given zero-based index. On successful element removal, the indices elements beyond the given index will reduced by one.

      Parameters:
        `arrayProperty` - Property value of the array to be modified.
        `index` - 0-based index of the element to be removed from the given array.
      Throws:
        `NullPointerException` - The given array property value is `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current size of the given array.

    - #### insertElement

          void insertElement(PropertyValue arrayProperty,
                             @UInt32
                             int index,
                             PropertyValue element)
                      throws NullPointerException,
                             IllegalPropertyValueException,
                             IndexOutOfBoundsException,
                             BadTypeException

      Inserts the value of the given element into the given array property. The index is zero-based and must be less than the value returned by `getCount(PropertyValue)`. The property value must be of the same type as returned by `getType()`. Elements at the given index and above will have their indices increased by one to accommodate the new element.

      Parameters:
        `arrayProperty` - Property value corresponding to an array.
        `index` - 0-based index at which to insert the given element into the given array.
        `element` - Element to insert into the given array at the given index.
      Throws:
        `NullPointerException` - The given array property value and/or the given element is/are `null`.
        `IllegalPropertyValueException` - The given property value type does not match this variable size array property definition.
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current size of the given array.
        `BadTypeException` - The given element is of the wrong type to be inserted into the array.
      See Also:
        `appendElement(PropertyValue, PropertyValue)`, `prependElement(PropertyValue, PropertyValue)`, `setElementAt(PropertyValue, int, PropertyValue)`

    - #### clone

          TypeDefinitionVariableArray clone()

      Create a cloned copy of this variable array type definition.

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

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