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

tv.amwa.maj.meta

## Interface TypeDefinitionExtendibleEnumeration

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

      public interface TypeDefinitionExtendibleEnumeration
      extends TypeDefinition

  Specifies the definition of a property type that can have one of an extendible set of AUID values. Each value is an enumeration element with its own name. The elements are specified as an array of identifiers and an array of names, where a single element is defined by the identifier and name and the same index of the arrays.

  The MAJ warehouse keeps a runtime inventory of elements for extendible enumeration types. A quick way to fill the inventory is to define a class containing static AUID values an annotating these as extendible enumeration items.

  See Also:
    `TypeCategory.ExtEnum`, `Warehouse.registerExtendibleEnumerationElements(Class)`, `Warehouse.registerExtendibleEnumerationElement(String, String, AUID)`, `Warehouse.lookupExtendibleEnumeration(String)`, `ExtendibleEnumerationItem`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendElement(AUID value, String name)` Appends the given element, a name and AUID pair, to this extendible enumeration type definition.
    `TypeDefinitionExtendibleEnumeration` | `clone()` Create a cloned copy of this extendible enumeration type definition.
    `int` | `countElements()` Returns the number of enumeration elements of this extendible enumeration type definition.
    `PropertyValue` | `createValueFromName(String name)` Creates a property value defined by this extendible enumeration type definition using the given name.
    `AUID` | `getAUIDFromName(String elementName)` Returns the identifier of the enumeration element associated with the given name, as defined by this extendible enumeration type definition.
    `AUID` | `getAUIDValue(PropertyValue enumerationProperty)` Returns the AUID value associated with the given extendible enumeration property value according to this extendible enumeration type definition.
    `String` | `getElementName(int index)` Returns the name of the enumeration element at the given index in the list of elements of this extendible enumeration type definition.
    `AUID` | `getElementValue(int index)` Returns the AUID value for the enumeration element at the given index of in the list of elements of this extendible enumeration type definition.
    `String` | `getNameFromAUID(AUID elementValue)` Returns the name of the enumeration element associated with the given AUID value, as defined by this extendible enumeration type definition.
    `String` | `getNameFromValue(PropertyValue enumerationProperty)` Returns the name associated with the given property value, as defined by this extendible enumeration type definition.
    `void` | `setAUIDValue(PropertyValue enumerationProperty, AUID value)` Sets the value of the given extendible enumeration property value to the given AUID that identifies an element of this extendible enumeration type definition.

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

    - #### createValueFromName

          PropertyValue createValueFromName(@AAFString
                                            String name)
                                     throws NullPointerException,
                                            InvalidParameterException

      Creates a property value defined by this extendible enumeration type definition using the given name. The name is checked to see that it is in the list of names defining elements of this enumeration.

      Parameters:
        `name` - Name to use to create a new extendible enumeration property value.
      Returns:
        New extendible enumeration property value corresponding to the given name.
      Throws:
        `NullPointerException` - The given name is `null`.
        `InvalidParameterException` - The given name does not match an element of this extendible enumeration type definition.
      See Also:
        `setAUIDValue(PropertyValue, AUID)`

    - #### countElements

          @UInt32
          int countElements()

      Returns the number of enumeration elements of this extendible enumeration type definition.

      Returns:
        Number of enumeration elements of this extendible enumeration type definition.

    - #### getElementValue

          AUID getElementValue(@UInt32
                               int index)
                        throws IndexOutOfBoundsException

      Returns the AUID value for the enumeration element at the given index of in the list of elements of this extendible enumeration type definition.

      Parameters:
        `index` - Index of the required AUID value.
      Returns:
        AUID value for the enumeration element at the given index of the list of elements of this extendible enumeration type definition.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the list of elements of this extendible enumeration type definition.

    - #### getElementName

          @AAFString
          String getElementName(@UInt32
                                           int index)
                                    throws IndexOutOfBoundsException

      Returns the name of the enumeration element at the given index in the list of elements of this extendible enumeration type definition.

      Parameters:
        `index` - Index of the required name.
      Returns:
        Name for the enumeration element at the given index in the list of elements of this extendible enumeration type definition.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for this extendible enumeration type definition.

    - #### getNameFromValue

          @AAFString
          String getNameFromValue(PropertyValue enumerationProperty)
                                      throws NullPointerException,
                                             IllegalPropertyValueException

      Returns the name associated with the given property value, as defined by this extendible enumeration type definition.

      Parameters:
        `enumerationProperty` - Property value to lookup the name of.
      Returns:
        Name of the enumeration element of the given extendible enumeration property value.
      Throws:
        `NullPointerException` - The given extendible enumeration property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this extendible enumeration type definition.

    - #### getNameFromAUID

          @AAFString
          String getNameFromAUID(AUID elementValue)
                                     throws NullPointerException,
                                            BadParameterException

      Returns the name of the enumeration element associated with the given AUID value, as defined by this extendible enumeration type definition.

      Parameters:
        `elementValue` - Value to use to lookup the element name.
      Returns:
        Name associated with the given value in this extendible enumeration type definition.
      Throws:
        `NullPointerException` - The given identifier is `null`.
        `BadParameterException` - The given value is not found in the list of values of this extendible enumeration type definition.
      See Also:
        `getAUIDFromName(String)`

    - #### getAUIDFromName

          AUID getAUIDFromName(@AAFString
                               String elementName)
                        throws NullPointerException,
                               BadParameterException

      Returns the identifier of the enumeration element associated with the given name, as defined by this extendible enumeration type definition.

      Parameters:
        `elementName` - Name to use to lookup the element identifier.
      Returns:
        Identifier associated with the given name in this extendible enumeration type definition.
      Throws:
        `NullPointerException` - The given element name is `null`.
        `BadParameterException` - The given element name is not known for in the list of values of this extendible enumeration type definition.
      See Also:
        `getNameFromAUID(AUID)`

    - #### getAUIDValue

          AUID getAUIDValue(PropertyValue enumerationProperty)
                     throws NullPointerException,
                            IllegalPropertyValueException

      Returns the AUID value associated with the given extendible enumeration property value according to this extendible enumeration type definition.

      Parameters:
        `enumerationProperty` - Extensible enumeration property value to find the associated AUID value for.
      Returns:
        AUID associated with the given property value by this extendible enumeration type definition.
      Throws:
        `NullPointerException` - The given extendible enumeration property value is `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this extendible enumeration type definition.
      See Also:
        `getNameFromAUID(AUID)`, `getAUIDFromName(String)`

    - #### setAUIDValue

          void setAUIDValue(PropertyValue enumerationProperty,
                            AUID value)
                     throws NullPointerException,
                            IllegalPropertyValueException,
                            BadParameterException

      Sets the value of the given extendible enumeration property value to the given AUID that identifies an element of this extendible enumeration type definition.

      Parameters:
        `enumerationProperty` - Extensible enumeration property value to change.
        `value` - New value to set the given property value to.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`.
        `IllegalPropertyValueException` - The given property value is not defined by this extendible enumeration type definition.
        `BadParameterException` - The given enumeration value identifier does not identifiy an element of this extendible enumeration type.
      See Also:
        `getNameFromAUID(AUID)`, `getAUIDFromName(String)`, `createValueFromName(String)`

    - #### appendElement

          void appendElement(AUID value,
                             @AAFString
                             String name)
                      throws NullPointerException,
                             DuplicateException

      Appends the given element, a name and AUID pair, to this extendible enumeration type definition.

      Parameters:
        `value` - AUID for the new enumeration element to append.
        `name` - Name for the new enumeration element to append.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`.
        `DuplicateException` - Appending the given enumeration element would introduce a duplicate value and/or duplicate name.

    - #### clone

          TypeDefinitionExtendibleEnumeration clone()

      Create a cloned copy of this extendible enumeration type definition.

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

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