Media Authoring
with Java API

tv.amwa.maj.iface
Interface TypeDefinitionVariableArray

All Superinterfaces:
MetaDefinition, TypeDefinition
All Known Implementing Classes:
TypeDefinitionVariableArray

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:

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

Author:
Richard Cartwright
See Also:
makeTypeDefinitionVariableArray(), TypeCategory.VariableArray, TypeDefinitionFixedArray, TypeDefinitionSet

Method Summary
 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.
 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.iface.TypeDefinition
createValue, getTypeCategory
 
Methods inherited from interface tv.amwa.maj.iface.MetaDefinition
getAUID, getDescription, getName, setDescription, setName
 

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)

Media Authoring
with Java API

(c) 2007-2008 Richard Cartwright, all rights reserved. Subject to the terms of the AAF SDK Public Source License.