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

tv.amwa.maj.meta

## Interface TypeDefinitionRecord

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

      public interface TypeDefinitionRecord
      extends TypeDefinition

  Specifies the definition of a property type that consists of an ordered set of fields, where each field has a name and type.

  A number of built-in record type definitions are supported in the MAJ API by interfaces specified in the record package. Record type definitions provide a mechanism for extending the range of data types supported in AAF. In the MAJ API, any interface that has a set and get method for each of the fields of a record can be used to represent a value of that type.

  As an example, consider a person record type consisting of a first name, surname and age, the following record fields would be defined:

  - field 1: "firstName" of type string;
  - field 2: "surname" of type string;
  - field 3: "age" of type integer, in this case a UInt16.

  Using a call to `createValueFromObject(Object)`, a record property value of person type can be created from any class that implements the following Java interface:

       public interface Person {
           public String getFirstName();
           public void setFirstName(String firstName);
           public String getSurname();
           public void setSurname();
           public @UInt16 short getAge();
           public void setAge(@UInt16 short age);
       }

  The interface must be set when the class is instantiated and can be queried with the `getSpecification()` method. If an implementation is avaialble, this can be queried with `getImplementation()`.

  See Also:
    `TypeCategory.Record`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `TypeDefinitionRecord` | `clone()` Create a cloned copy of this record type definition.
    `PropertyValue` | `createValueFromObject(Object initialData)` Creates and returns a new record property value that is initialized using the given Java object.
    `PropertyValue` | `createValueFromValues(PropertyValue[] fieldValues)` Creates and returns a new record property value from the given array of property values, matching the elements of the given array to the fields of a new record value by index into the list of fields of this record type definition.
    `int` | `getCount()` Returns the number of fields stored in a record defined by this record type definition.
    `Class<?>` | `getImplementation()` Returns an implementation of the specified interface if available; otherwise `null`.
    `String` | `getMemberName(int index)` Returns the name of the field of a record defined by this record type definition at the given index into the list of fields.
    `TypeDefinition` | `getMemberType(int index)` Returns the type of the field of a record defined by this record type definition at the given index into the list of fields.
    `Object` | `getObject(PropertyValue recordProperty)` Returns the object representing the record value.
    `Class<?>` | `getSpecification()` Returns the interface that specifies acceptable implementations of record values of this type.
    `PropertyValue` | `getValue(PropertyValue recordProperty, int index)` Returns the property value of one of the fields of the given record property value, where the value to return is determined by an index into the list of fields of this record type definition.
    `PropertyValue` | `getValue(PropertyValue recordProperty, String fieldName)` Returns the property value of one of the fields of the given record property value, where the value to return corresponds to the given field name.
    `void` | `setObject(PropertyValue recordProperty, Object data)` Sets the value of the given record property value using the given Java object.
    `void` | `setValue(PropertyValue recordProperty, int index, PropertyValue fieldProperty)` Sets the value of a field of the given record property value, determined by index into the list of fields of its record type definition.
    `void` | `setValue(PropertyValue recordProperty, String fieldName, PropertyValue fieldProperty)` Sets the value of a field of the given record property value, determined by field name, to be the given field property 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

    - #### getMemberType

          TypeDefinition getMemberType(@UInt32
                                       int index)
                                throws IndexOutOfBoundsException

      Returns the type of the field of a record defined by this record type definition at the given index into the list of fields.

      Parameters:
        `index` - 0-based index into the record type definition's fields.
      Returns:
        Field type at the given index.
      Throws:
        `IndexOutOfBoundsException` - The index is outside the acceptable range for the list of fields of this record type definition.

    - #### getMemberName

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

      Returns the name of the field of a record defined by this record type definition at the given index into the list of fields.

      Parameters:
        `index` - 0-based index into the record type definition's list of fields.
      Returns:
        Field name at the given index.
      Throws:
        `IndexOutOfBoundsException` - The index is outside the acceptable range for the number of fields of this record type definition.

    - #### createValueFromValues

          PropertyValue createValueFromValues(PropertyValue[] fieldValues)
                                       throws NullPointerException,
                                              IllegalArgumentException,
                                              BadTypeException

      Creates and returns a new record property value from the given array of property values, matching the elements of the given array to the fields of a new record value by index into the list of fields of this record type definition.

      Parameters:
        `fieldValues` - Array of property values to set for the new record property value.
      Returns:
        Newly created record property value from the given array of property values.
      Throws:
        `NullPointerException` - The given array of field values is `null` or one or more of the elements of the array is `null`.
        `IllegalArgumentException` - The given array is of a different size from that defined by the record type definition and returned by `getCount()`.
        `BadTypeException` - One or more of the given property values is of a type that does not match the one defined for the field at the equivalent index in the list of fields of this record type definition.

    - #### createValueFromObject

          PropertyValue createValueFromObject(Object initialData)
                                       throws BadTypeException

      Creates and returns a new record property value that is initialized using the given Java object. The Java reflection API is used to discover if the fields of the record, matched by name, are readable from the given object, either as public fields or as public `get...` methods. The type of each field in the Java object must be compatible with the type definition defined for that field in this record type definition.

      Note that the object may define more fields than the number of elements of the record. If this is the case, the record property value will contain less information than the given object instance. Be aware that a future call to `getObject(PropertyValue)` with a record property created by this method may result in a different Java object value.

      Parameters:
        `initialData` - Object to use to set the values of the a new record property value. A `null` value is permitted.
      Returns:
        Newly created record property value, created using the the current value of the given object.
      Throws:
        `BadTypeException` - The type of the object cannot be converted to the interface specification defined in this record type definition.
      See Also:
        `Class.getFields()`, `Class.getMethods()`, `createValueFromValues(PropertyValue[])`

    - #### getValue

          PropertyValue getValue(PropertyValue recordProperty,
                                 @UInt32
                                 int index)
                          throws NullPointerException,
                                 IllegalPropertyValueException,
                                 IndexOutOfBoundsException

      Returns the property value of one of the fields of the given record property value, where the value to return is determined by an index into the list of fields of this record type definition.

      Parameters:
        `recordProperty` - Property value containing a record that is to have a value returned.
        `index` - 0-based index into the array of fields of this record type definition that is used to determine the field of the given record property value to return.
      Returns:
        Member of the given record property value selected using the given index.
      Throws:
        `NullPointerException` - The given record property value is `null`.
        `IllegalPropertyValueException` - The type of the given property value does not match this record type definition.
        `IndexOutOfBoundsException` - The given index is not within the acceptable range for this record type definition.
      See Also:
        `getValue(PropertyValue, String)`

    - #### getValue

          PropertyValue getValue(PropertyValue recordProperty,
                                 String fieldName)
                          throws NullPointerException,
                                 IllegalPropertyValueException,
                                 IllegalArgumentException

      Returns the property value of one of the fields of the given record property value, where the value to return corresponds to the given field name.

      Parameters:
        `recordProperty` - Property value containing a record that is to have a value returned.
        `fieldName` - Name of the field value to retrieve.
      Returns:
        Property value containing the requested field value.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`.
        `IllegalPropertyValueException` - The type of the given property value does not match this record type definition.
        `IllegalArgumentException` - The given field name does not identify a field of this record type definition.

    - #### getObject

          Object getObject(PropertyValue recordProperty)
                    throws NullPointerException,
                           BadTypeException,
                           IllegalPropertyValueException

      Returns the object representing the record value. Note that the internal value is permitted to be `null`.

      This method is very similar to `recordProperty.getValue()` except that it checks the type definition matches this one first.

      Parameters:
        `recordProperty` - Property value containing a record to extract the field values from.
      Returns:
        New Java object with its values set by the fields of the given record property value.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`.
        `BadTypeException` - The types of the field properties of the record type definition cannot be converted to the types of the fields of an instance of the given class.
        `IllegalPropertyValueException` - The given property value is not defined by a compatible record type definition.
      See Also:
        `createValueFromObject(Object)`, `setObject(PropertyValue, Object)`, `PropertyValue.getValue()`

    - #### setValue

          void setValue(PropertyValue recordProperty,
                        @UInt32
                        int index,
                        PropertyValue fieldProperty)
                 throws NullPointerException,
                        IllegalPropertyValueException,
                        IndexOutOfBoundsException,
                        BadTypeException

      Sets the value of a field of the given record property value, determined by index into the list of fields of its record type definition. The field property must be of a type that is compatible with the type at the given index, as returned by `getMemberType(int)` for the same index.

      Parameters:
        `recordProperty` - Property value containing a record that is to have one of its fields set.
        `index` - 0-based index into the record type definition defining the given record property value. This determines the name and required type of the record field.
        `fieldProperty` - Value to set as a field of the given record property value.
      Throws:
        `NullPointerException` - One or both of the property arguments is/are `null`.
        `IllegalPropertyValueException` - The type of the given property definition does not match this record type definition.
        `IndexOutOfBoundsException` - The given index is outside the range of the list of fields of this record type definition.
        `BadTypeException` - The type of the given field property value does not match that defined at the given index in the record type definition.
      See Also:
        `getValue(PropertyValue, int)`, `setValue(PropertyValue, String, PropertyValue)`

    - #### setValue

          void setValue(PropertyValue recordProperty,
                        String fieldName,
                        PropertyValue fieldProperty)
                 throws NullPointerException,
                        IllegalPropertyValueException,
                        IllegalArgumentException,
                        BadTypeException

      Sets the value of a field of the given record property value, determined by field name, to be the given field property value. The field property must be of a type that is compatible with the type of the field specified in the list of fields of this property.

      Parameters:
        `recordProperty` - Property value containing a record that is to have one of its fields set.
        `fieldName` - Name of the field to set the value for within the given record property value.
        `fieldProperty` - Value to set the field to.
      Throws:
        `NullPointerException` - One or more or the arguments is/are `null` and all are required.
        `IllegalPropertyValueException` - The type of the given record property definition does not match this record type definition.
        `IllegalArgumentException` - The field name is not known as a field of this record type definition.
        `BadTypeException` - The type of the given field property value does not match that defined for the field with given name in this record type definition.
      See Also:
        `getValue(PropertyValue, String)`, `setValue(PropertyValue, int, PropertyValue)`

    - #### setObject

          void setObject(PropertyValue recordProperty,
                         Object data)
                  throws NullPointerException,
                         IllegalPropertyValueException,
                         BadTypeException

      Sets the value of the given record property value using the given Java object. The Java reflection API is used to discover if the fields of the record are readable from the given object, either as public fields or public `get...` methods. The types of the fields of the given object must be compatible with the type definitions of the matching fields in this record type definition.

      Note that the object may define more fields than the number of elements of the record. If this is the case, the record property value will contain less information than the given object. Be aware that a subsequent call to `getObject(PropertyValue)` with a record property value created by this method may result in a different object value.

      Parameters:
        `recordProperty` - Property value containing a record that is to have its values set.
        `data` - A Java object that is used to set the fields of the given record property value.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`.
        `IllegalPropertyValueException` - The given object does not provide values for one or more of the record's values, or the given property value is not defined by a compatible record type definition.
        `BadTypeException` - One or more of the field types of the given object do not match or cannot be converted to the type of their equivalent property in this record type definition.
      See Also:
        `createValueFromObject(Object)`, `getObject(PropertyValue)`

    - #### getCount

          @UInt32
          int getCount()

      Returns the number of fields stored in a record defined by this record type definition.

      Returns:
        Number of fields stored in a record defined by this record type definition.

    - #### getSpecification

          Class<?> getSpecification()

      Returns the interface that specifies acceptable implementations of record values of this type.

      Returns:
        Interface specifying Java implementations of values of this type.
      See Also:
        `getImplementation()`

    - #### getImplementation

          Class<?> getImplementation()

      Returns an implementation of the specified interface if available; otherwise `null`.

      Returns:
        Implementation of the specified interface.
      See Also:
        `getSpecification()`

    - #### clone

          TypeDefinitionRecord clone()

      Create a cloned copy of this record type definition.

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

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