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

tv.amwa.maj.industry

## Annotation Type MediaProperty

-     @Documented
       @Retention(value=RUNTIME)
       @Target(value={METHOD,FIELD})
      public @interface MediaProperty

  Labels a get method of a Java class to indicate that it provides access to the property value of an AAF class. The annotation is used to create a property definition for the property at runtime, enabling the dynamic extension of a meta dictionary. The class membership of a property is determined from the Java class of the annotated method.

  For singleton values and records, this labelled method should return an object representing that value. For compound values such as variable sized arrays and sets, a complete collection of values will be returned. For example, here are two methods labelled as AAF properties:

  - `Track.getTrackID()` returns a single integer value representing identity of the track for a property of type `UInt32`;
  - `Package.getPackageTracks()` returns the list of tracks within a package for a property of type "StrongReferenceVector of Track".

  A symbol name must be provided which will be used to name an element when writing or reading the property to an XML representation. Normally, the namespace for the element will be the same for the class that the property is a member of. A namespace can be specified to override this if required. Other aspects of serialization to and from XML can be configured with `isXMLCDATA()`, `isXMLAttribute()` and `flattenXML()`.

  See Also:
    `PropertyDefinition`, `ClassDefinition.getProperties(tv.amwa.maj.industry.MetadataObject)`, `PropertyValue`, `MediaPropertySetter`, `TypeDefinitions.PropertyDefinitionWeakReference`, `TypeDefinitions.PropertyDefinitionStrongReference`, `TypeDefinitions.PropertyDefinitionStrongReferenceSet`, `TypeDefinitions.PropertyDefinitionWeakReferenceSet`

- - ### Required Element Summary

    Required Elements
    Modifier and Type | Required Element and Description
    --- | ---
    `String` | `definedName` Provides the registered name of this property within its class.
    `boolean` | `optional` Indicates whether this property is optional.
    `String` | `symbol` Provides the registered symbol used for this property when serialized to XML.
    `String` | `typeName` Provides the name of the type that specifies values of this property.
    `boolean` | `uniqueIdentifier` Indicates whether this property is a unique identifier for the class it is contained within.
    `int` | `uuid1` Provides the first 4 bytes of the unique AUID identification of this property as a UUID.
    `int` | `uuid2` Provides bytes 5 and 6 of the unique AUID identification of this property as a UUID.
    `int` | `uuid3` Provides bytes 7 and 8 of the unique AUID identification of this property as a UUID.
    `byte[]` | `uuid4` Provides bytes 9 to 16 of the unique AUID identification of this property as a UUID.

  - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `String[]` | `aliases` Provides alternative names that this property may be known by.
    `String` | `description` Provides a description of the property.
    `boolean` | `flattenXML` Determines whether an XML serialization of referenced values or collections of values should appear as a replacement for this element rather than contained within it.
    `boolean` | `isXMLAttribute` Determines whether an XML serialization of this value should appear as an attribute of the parent element rather than contained within its own element.
    `boolean` | `isXMLCDATA` Determines whether an XML serialization of this value should appear as the CDATA content of the parent element rather than contained within its own element.
    `String` | `namespace` Provides the XML namespace for this property.
    `int` | `pid` Prvoides the local identification for the property.
    `String` | `prefix` Provides the XML namespace prefix abbreviation for this property.
    `int` | `weight` Provides a weighting value for ordering property definitions or values when serialized to XML or listed in a collection.

- - ### Element Detail

    - #### uuid1

          public abstract int uuid1

      Provides the first 4 bytes of the unique AUID identification of this property as a UUID. This is bytes 9 to 12 if the identification is a SMPTE universal label.

      Returns:
        First 4 bytes of the identification of this property.
      See Also:
        `AUID.getData1()`, `MetaDefinition.getAUID()`

  - - #### uuid2

          public abstract int uuid2

      Provides bytes 5 and 6 of the unique AUID identification of this property as a UUID. This is bytes 13 and 14 if the identification is a SMPTE universal label.

      Returns:
        Bytes 5 and 6 of the identification of this property.
      See Also:
        `AUID.getData2()`, `MetaDefinition.getAUID()`

  - - #### uuid3

          public abstract int uuid3

      Provides bytes 7 and 8 of the unique AUID identification of this property as a UUID. This is bytes 15 and 16 if the identification is a SMPTE universal label.

      Returns:
        Bytes 7 and 8 of the identification of this property.
      See Also:
        `AUID.getData3()`, `MetaDefinition.getAUID()`

  - - #### uuid4

          public abstract byte[] uuid4

      Provides bytes 9 to 16 of the unique AUID identification of this property as a UUID. This is bytes 1 to 8 if the identification is a SMPTE universal label.

      Returns:
        Bytes 9 to 16 of the identification of this property.
      See Also:
        `AUID.getData4()`, `MetaDefinition.getAUID()`

  - - #### definedName

          public abstract String definedName

      Provides the registered name of this property within its class. The registered name must be unique within the class.

      Returns:
        Registered name for this property.
      See Also:
        `MetaDefinition.getName()`, `symbol()`, `ClassDefinition.lookupPropertyDefinition(String)`

  - - #### typeName

          public abstract String typeName

      Provides the name of the type that specifies values of this property. In the MAJ API, type names are resolved to using the `Warehouse.lookForType(String)` method.

      Returns:
        Type name for the type sepcifying values of this proeprty.
      See Also:
        `Warehouse.lookForType(String)`, `PropertyDefinition.getTypeDefinition()`, `TypeDefinitions.TypeDefinitionWeakReference`

  - - #### optional

          public abstract boolean optional

      Indicates whether this property is optional. An optional property can be omitted from any specification of an instance of its defining class.

      Returns:
        Is the property optional?
      See Also:
        `PropertyDefinition.getIsOptional()`, `PropertyNotPresentException`

  - - #### uniqueIdentifier

          public abstract boolean uniqueIdentifier

      Indicates whether this property is a unique identifier for the class it is contained within.

      Returns:
        Is this property a unique identifier for its defining class?
      See Also:
        `PropertyDefinition.getIsUniqueIdentifier()`

  - - #### symbol

          public abstract String symbol

      Provides the registered symbol used for this property when serialized to XML. The symbol should not include a namespace declaration. Symbols must be unique within a namespace whereas defined names only have to be unique within a class.

      Returns:
        Registered symbol for the property.
      See Also:
        `namespace()`

  - - #### aliases

          public abstract String[] aliases

      Provides alternative names that this property may be known by. The namespace for property names is unique within their member class. Take care not to overwrite the definition of another property. A warning will be generated if an alias overwrites a defined property name.

      As an example, the Name property of a text locator may be specified with symbols TextLocatorName and LocationName.

      Returns:
        List of alternative names for this property.
      See Also:
        `ClassDefinition.lookupPropertyDefinition(String)`
      Default:
        {}

  - - #### pid

          public abstract int pid

      Prvoides the local identification for the property. This may be used within a serialized value of the property to identify the property efficiently, as in MXF. If the property is omitted or set to zero, the local identification must be determined dynamically at runtime.

      Returns:
        Local identification for this property.
      See Also:
        `PropertyDefinition.getLocalIdentification()`
      Default:
        0

  - - #### description

          public abstract String description

      Provides a description of the property.

      Returns:
        Description of the property.
      See Also:
        `MediaClass.description()`
      Default:
        ""

  - - #### namespace

          public abstract String namespace

      Provides the XML namespace for this property. If none is defined, the one for the class the property is a member of is used. When serialized to XML, the property will have the following `xmlns:` attribute included in its element name:

      `xmlns:`<namespaceAbbreviation>`="`<namespace>`"`
      Returns:
        Registered XML namespace for an element representing this property.
      See Also:
        `prefix()`, `MediaClass.namespace()`, `symbol()`
      Default:
        ""

  - - #### prefix

          public abstract String prefix

      Provides the XML namespace prefix abbreviation for this property. If none is defined, the one for the class the property is a member of is used.When serialized to XML, the property will have the following `xmlns:` attribute included in its element name:

      `xmlns:`<namespaceAbbreviation>`="`<namespace>`"`
      Returns:
        XML namespace for an element representing this property.
      See Also:
        `namespace()`, `MediaClass.prefix()`
      Default:
        ""

  - - #### isXMLCDATA

          public abstract boolean isXMLCDATA

      Determines whether an XML serialization of this value should appear as the CDATA content of the parent element rather than contained within its own element.

      Values are normally serialized to an element as follows:

           <Parent>
             <Child1>value1</Child1>
             <Child2>value2</Child2>
             ...
           </Parent>

      If this property has the symbol `Child2`, setting this flag to `true` causes the value of the property to be inserted as CDATA of element `Parent`:

           <Parent>
             <Child1>value1</Child1>
             value2
             ...
           </Parent>

      Returns:
        Should the value of this property appear as the CDATA content of the parent element?
      Default:
        false

  - - #### isXMLAttribute

          public abstract boolean isXMLAttribute

      Determines whether an XML serialization of this value should appear as an attribute of the parent element rather than contained within its own element. Only elements of the following types are suitable for use as attributes:

      - integer type;
      - string type;
      - rename type when it renames another type in this list;
      - enumeration type;
      - extendible enumeration type;
      - record type when the underlying value has a representation as a simple string, such as AUID.

      Values are normally serialized to an element as follows:

           <Parent>
             <Child1>value1</Child1>
             <Child2>value2</Child2>
             ...
           </Parent>

      If this property has the symbol `Child2`, setting this flag to `true` causes the value of the property to be set as an attribute of `Parent`:

           <Parent Child2="value2">
             <Child1>value1</Child1>
             ...
           </Parent>

      Returns:
        Should the value of this property appear as an attribute of the parent element?
      Default:
        false

  - - #### flattenXML

          public abstract boolean flattenXML

      Determines whether an XML serialization of referenced values or collections of values should appear as a replacement for this element rather than contained within it.

      Values are normally serialized to an element as follows:

           <Parent>
             <ThisProperty>
               <Child attribute1="atval1">value1</Child>
               <Child>value2</Child>
               ...
             </ThisProperty>
             ...
           </Parent>

      Setting this flag to `true` causes the values of the children of this property to be inserted into this property's parent directly with the same symbol as this property:

           <Parent>
             <ThisProperty attribute1="atval1">value1</ThisProperty>
             <ThisProperty>value2</ThisProperty>
             ...
           </Parent>

      Attributes are also carried to the higher level.

      Returns:
        Should the value of this property appear as the CDATA content of the parent element?
      Default:
        false

  - - #### weight

          public abstract int weight

      Provides a weighting value for ordering property definitions or values when serialized to XML or listed in a collection. The property with the lowest weight appears first. If this value is omitted, a value is computed from the order of the property definition within the class hierarchy and defining class.

      Returns:
        Relative weight for ordering the property in a list.
      See Also:
        `PropertyDefinition.getWeight()`
      Default:
        0

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