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

tv.amwa.maj.meta

## Interface PropertyDefinition

- All Superinterfaces:
    Comparable<PropertyDefinition>, MetadataObject, MetaDefinition, WeakReferenceTarget
  All Known Subinterfaces:
    PropertyWrapperDefinition
  All Known Implementing Classes:
    PropertyDefinitionImpl, PropertyWrapperDefinitionImpl

      public interface PropertyDefinition
      extends MetaDefinition, Comparable<PropertyDefinition>

  Specifies the description of a property allowed for a class.

  A property definition is used to indicate a particular property within a class. It defines the name and type of a property that is used to set the value of an object of the class. Property definitions should be created through `registerNewPropertyDefinition()` or `registerOptionalPropertyDefinition()`.

  See Also:
    `ClassDefinition.registerNewPropertyDefinition(AUID, String, String[], String, String, boolean, boolean, Short)`, `ClassDefinition.registerOptionalPropertyDefinition(AUID, String, String[], String, String)`, `ClassDefinition.getPropertyDefinitions()`, `ClassDefinition.getAllPropertyDefinitions()`, `Warehouse.lookForClass(String)`, `MediaProperty`, `PropertyValue`, `TypeDefinitions.PropertyDefinitionWeakReference`, `TypeDefinitions.PropertyDefinitionWeakReferenceSet`, `TypeDefinitions.PropertyDefinitionStrongReference`, `TypeDefinitions.PropertyDefinitionStrongReferenceSet`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `PropertyDefinition` | `clone()` Create a cloned copy of this property definition.
    `boolean` | `getFlattenXML()` 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` | `getIsOptional()` Returns `true` for a property that is optional and `false` for a mandatory property.
    `boolean` | `getIsUniqueIdentifier()` Returns `true` for a property that provides a unique identifier for its associated object; otherwise `false`.
    `boolean` | `getIsXMLAttribute()` Determines whether the content of this property should be sereialized to XML as an XML attribute of the owning class rather than as a separate element.
    `boolean` | `getIsXMLCDATA()` Determines whether the content of this property should be serialized to XML as the CDATA content of the owning class rather than as a separate element.
    `short` | `getLocalIdentification()` Returns the local identification associated with this property definition, which is used to identify the property within the scope of its associated class, as returned by `getMemberOf()`.
    `ClassDefinition` | `getMemberOf()` Returns the class definition for the class that this property definition defines a property for.
    `AUID` | `getPropertyType()` Returns the identifier for the type of this property.
    `PropertyValue` | `getPropertyValue(MetadataObject metadataObject)` Returns the requested property value of the given object.
    `String` | `getSymbol()` Returns the symbol name for this property, which is the same as its tag name in registered data XML.
    `TypeDefinition` | `getTypeDefinition()` Returns the property type of the defined property.
    `int` | `getWeight()` Returns the relative weight of this property definition, which is used when generating a list of properties for a class or ordering elements when serializing to XML.
    `boolean` | `isPropertyPresent(MetadataObject metadataObject)` Returns `true` if this is legal and present for the given object; otherwise returns `false`.
    `void` | `omitOptionalProperty(MetadataObject metadataObject)` Omits this property from the given object if it is legal, optional and is present.
    `void` | `setMemberOf(ClassDefinition memberOf)` Sets the class definition of the the class that this property definition is associated with.
    `void` | `setPropertyValue(MetadataObject metadataObject, PropertyValue propertyValue)` Sets the value of this property on the given object.

    - ### Methods inherited from interface tv.amwa.maj.meta.MetaDefinition

      `appendMetadictXML, deepEquals, equals, getAAFNamesInUse, getAliases, getAUID, getDescription, getName, getNamespace, getPrefix, hashCode, setAAFNamesInUse, setDescription, setName, setNamespace, setPrefix, setSymbol, toString`

    - ### Methods inherited from interface tv.amwa.maj.industry.WeakReferenceTarget

      `getWeakTargetReference`

    - ### Methods inherited from interface java.lang.Comparable

      `compareTo`

- - ### Method Detail

    - #### getTypeDefinition

          TypeDefinition getTypeDefinition()

      Returns the property type of the defined property.

      Returns:
        Type definition for this property definition.
      See Also:
        `getPropertyType()`

    - #### getPropertyType

          AUID getPropertyType()

      Returns the identifier for the type of this property.

      Returns:
        Identifier for the type of this property.
      See Also:
        `getTypeDefinition()`

    - #### getIsOptional

          @Bool
          boolean getIsOptional()

      Returns `true` for a property that is optional and `false` for a mandatory property. Optional properties can be omitted from an objects persistent representation.

      Returns:
        Is the property optional?

    - #### getIsUniqueIdentifier

          @Bool
          boolean getIsUniqueIdentifier()
                                       throws PropertyNotPresentException

      Returns `true` for a property that provides a unique identifier for its associated object; otherwise `false`.

      Returns:
        Is this property a unique identifier for an object it is part of?
      Throws:
        `PropertyNotPresentException` - The optional is unique identifier property is not present in this property definition.

    - #### getLocalIdentification

          @UInt16
          short getLocalIdentification()

      Returns the local identification associated with this property definition, which is used to identify the property within the scope of its associated class, as returned by `getMemberOf()`. A value of zero indicates that no specified value is available and a unique tag should be generated dynamically on serialization.

      Returns:
        Local identification associated with this property definition.
      See Also:
        `PrimerPack.lookupLocalTag(AUID)`

    - #### getMemberOf

          ClassDefinition getMemberOf()
                               throws PropertyNotPresentException

      Returns the class definition for the class that this property definition defines a property for. This property is optional in the MAJ API but is almost always available in the implementation.

      Returns:
        Class definition of the class that this property definition is associated with.
      Throws:
        `PropertyNotPresentException` - The optional member of a class property is not present in this property definition.
      See Also:
        `ClassDefinition.getPropertyDefinitions()`

    - #### setMemberOf

          void setMemberOf(ClassDefinition memberOf)

      Sets the class definition of the the class that this property definition is associated with.

      Parameters:
        `memberOf` - Class definition of the class that this property definition is associated with.

    - #### getPropertyValue

          PropertyValue getPropertyValue(MetadataObject metadataObject)
                                  throws NullPointerException,
                                         IllegalPropertyException,
                                         PropertyNotPresentException,
                                         IllegalArgumentException

      Returns the requested property value of the given object. The desired property data is identified by this property definition.

      Parameters:
        `metadataObject` - Object with this property to retrieve the value from.
      Returns:
        This property value extracted from the object.
      Throws:
        `NullPointerException` - The given metadata object is `null`.
        `IllegalPropertyException` - The given object does not have this property.
        `PropertyNotPresentException` - The given property is optional, but not currently present in this instance of the class.
        `IllegalArgumentException` - An error occurred when trying to invoke the underlying class' method.
      See Also:
        `setPropertyValue(MetadataObject, PropertyValue)`, `MediaEngine.getPropertyValue(MetadataObject, String)`

    - #### setPropertyValue

          void setPropertyValue(MetadataObject metadataObject,
                                PropertyValue propertyValue)
                         throws NullPointerException,
                                IllegalPropertyException,
                                IllegalArgumentException

      Sets the value of this property on the given object. If the selected property is optional but not yet present, this method will make the property present before setting its value.

      Parameters:
        `metadataObject` - Object to set this property for.
        `propertyValue` - Value to set for the property.
      Throws:
        `NullPointerException` - One or both of the arguments is `null`.
        `IllegalPropertyException` - The given property is not defined on the given metadata object.
        `IllegalArgumentException` - An error occurred when trying to invole the underlying class' method.
      See Also:
        `getPropertyValue(MetadataObject)`, `getTypeDefinition()`, `TypeDefinition.createValue(Object)`

    - #### isPropertyPresent

          @Bool
          boolean isPropertyPresent(MetadataObject metadataObject)
                                   throws NullPointerException,
                                          IllegalPropertyException

      Returns `true` if this is legal and present for the given object; otherwise returns `false`.

      Parameters:
        `metadataObject` - Object to use to check for the presence of this property.
      Returns:
        Is the given property present for this interchange object?
      Throws:
        `NullPointerException` - The given metadata object is `null`.
        `IllegalPropertyException` - The given property is illegal for this interchange object's class.
      See Also:
        `ClassDefinition.getPropertyDefinitions()`, `PropertyNotPresentException`, `omitOptionalProperty(MetadataObject)`, `MediaEngine.isPropertyPresent(MetadataObject, String)`

    - #### omitOptionalProperty

          void omitOptionalProperty(MetadataObject metadataObject)
                             throws NullPointerException,
                                    IllegalPropertyException,
                                    IllegalArgumentException

      Omits this property from the given object if it is legal, optional and is present.

      Parameters:
        `metadataObject` - Object to request that this property is omitted.
      Throws:
        `NullPointerException` - The given metadata object is `null`.
        `IllegalPropertyException` - The given metadata object does not have this property or the property is not optional.
        `IllegalArgumentException` - An error occurred when trying to omit the optional property on the underlying class.
      See Also:
        `ClassDefinition.getPropertyDefinitions()`, `ClassDefinition.getProperties(MetadataObject)`, `isPropertyPresent(MetadataObject)`

    - #### getSymbol

          @AAFString
          String getSymbol()

      Returns the symbol name for this property, which is the same as its tag name in registered data XML. Symbol names provide a namespace with unique names for all SMPTE registered class names and property names.

      Specified by:
        `getSymbol` in interface `MetaDefinition`
      Returns:
        Symbol name of this class.
      See Also:
        `MediaProperty.symbol()`

    - #### getWeight

          @Int32
          int getWeight()

      Returns the relative weight of this property definition, which is used when generating a list of properties for a class or ordering elements when serializing to XML. The lowest weight value appears first. The default value is 0.

      The weight value is MAJ API specific and has been introduced to support XML formats that require elements to be in a sequential order, such as the Broadcast Exchange Format (BXF, SMPTE 2021-2008).

      Returns:
        Relative weight for ordering the property in a list.
      See Also:
        `MediaProperty.weight()`

    - #### getIsXMLCDATA

          boolean getIsXMLCDATA()

      Determines whether the content of this property should be serialized to XML as the CDATA content of the owning class rather than as a separate element.

      Returns:
        Should the value of this property be serialized to XML as the CDATA content of the owning class?
      See Also:
        `MediaProperty.isXMLCDATA()`

    - #### getIsXMLAttribute

          boolean getIsXMLAttribute()

      Determines whether the content of this property should be sereialized to XML as an XML attribute of the owning class rather than as a separate element.

      Returns:
        Should the value of this property be sereialized to XML as an XML attribute of the owning class?
      See Also:
        `MediaProperty.isXMLAttribute()`

    - #### getFlattenXML

          boolean getFlattenXML()

      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. The replaced elements will have their symbol changed to match the symbol of this element.

      Values are normally serialized to an element as follows:

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

      When this flag is set to `true`, 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 an XML serialization of referenced values or collections of values should appear as a replacement for this element rather than contained within it?
      See Also:
        `MediaProperty.flattenXML()`

    - #### clone

          PropertyDefinition clone()

      Create a cloned copy of this property definition.

      Specified by:
        `clone` in interface `MetaDefinition`
      Returns:
        Cloned copy of this property definition.

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