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

tv.amwa.maj.meta.impl

## Class PropertyDefinitionImpl

- java.lang.Object
- - tv.amwa.maj.meta.impl.MetaDefinitionImpl
  - - tv.amwa.maj.meta.impl.PropertyDefinitionImpl

- All Implemented Interfaces:
    Serializable, Cloneable, Comparable<PropertyDefinition>, CommonConstants, MetadataObject, WeakReferenceTarget, XMLSerializable, MetaDefinition, PropertyDefinition, DefinitionType
  Direct Known Subclasses:
    PropertyWrapperDefinitionImpl

      @MediaClass(uuid1=218169601,
                  uuid2=514,
                  uuid3=0,
                  uuid4={6,14,43,52,2,6,1,1},
                  definedName="PropertyDefinition",
                  description="The PropertyDefinition class describes properties allowed for a class.",
                  symbol="PropertyDefinition")
      public class PropertyDefinitionImpl
      extends MetaDefinitionImpl
      implements PropertyDefinition, Serializable, XMLSerializable, CommonConstants, Comparable<PropertyDefinition>

  Implementation of a AAF property definition, which describes properties allowed for a class.

  The preferred method of creating and managing property definitions in this Java implementation is by annotating get methods on class implementations with the `MediaProperty` annotation. Property definitions are then created and attached to their appropriate class definition using `ClassDefinitionImpl.forClass(Class)`.

  See Also:
    `PropertyDefinition`, `MediaProperty`, `tv.amwa.maj.model.InterchangeObject#getProperties()`, `PropertyValue`, `TypeDefinitions.PropertyDefinitionWeakReference`, `TypeDefinitions.PropertyDefinitionStrongReference`, `TypeDefinitions.PropertyDefinitionStrongReferenceSet`, `TypeDefinitions.PropertyDefinitionWeakReferenceSet`, Serialized Form

- - ### Field Summary

    - ### Fields inherited from interface tv.amwa.maj.constant.CommonConstants

      `AAF_METADICT_NAMESPACE, AAF_METADICT_PREFIX, AAF_XML_NAMESPACE, AAF_XML_PREFIX, ApplicationPluginObjectID, ApplicationPluginsID, MAX_NUM_RGBA_COMPS, MemberOfID, ObjectClassID, ParentClassID, PropertiesID, XMLClassIDAsAttributeName`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PropertyDefinitionImpl(AUID identification, String name, String type, ClassDefinition memberOf, boolean isOptional)` Creates and initializes a new property definition, which describes an allowed property of a `class definition`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendMetadictXML(Node metadict, String namespace, String prefix)` Append an XML representation of this meta definition to the given XML node.
    `void` | `appendXMLChildren(Node parent)` Append extra child elements to the given parent node to serialize the value of an object to an XML fragment.
    `PropertyDefinition` | `clone()` Create a cloned copy of this meta definition.
    `int` | `compareTo(PropertyDefinition o)`
    `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 `PropertyDefinition.getMemberOf()`.
    `ClassDefinition` | `getMemberOf()` Returns the class definition for the class that this property definition defines a property for.
    `MethodBag` | `getMethodBag()`
    `String` | `getNamespace()` Returns the namespace in which the subject of this meta definition is defined.
    `String` | `getPrefix()` Returns the namespace prefix to use when serializing a value of the subject of this meta definition to XML.
    `AUID` | `getPropertyType()` Returns the identifier for the type of this property.
    `PropertyValue` | `getPropertyValue(MetadataObject metadataObject)` Returns the requested property value of the given object.
    `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.
    `static void` | `initalizePropertyNameMap()`
    `static boolean` | `initializeIsOptional()`
    `static short` | `initializeLocalIdentification()`
    `static AUID` | `initializePropertyType()`
    `boolean` | `isPropertyPresent(MetadataObject metadataObject)` Returns `true` if this is legal and present for the given object; otherwise returns `false`.
    `String` | `nameToAAFName(String name)`
    `void` | `omitOptionalProperty(MetadataObject metadataObject)` Omits this property from the given object if it is legal, optional and is present.
    `void` | `setAnnotatedGetter(Method getter)`
    `void` | `setIsOptional(boolean isOptional)`
    `void` | `setIsUniqueIdentifier(Boolean isUniqueIdentifier)`
    `void` | `setLocalIdentification(Short localIdentification)`
    `void` | `setMemberOf(ClassDefinition memberOf)` Sets the class definition of the the class that this property definition is associated with.
    `void` | `setPropertyType(AUID propertyType)`
    `void` | `setPropertyValue(MetadataObject metadataObject, PropertyValue propertyValue)` Sets the value of this property on the given object.
    `void` | `setTypeDefinition(TypeDefinition type)`

    - ### Methods inherited from class tv.amwa.maj.meta.impl.MetaDefinitionImpl

      `aafNameToName, deepEquals, equals, getAAFNamesInUse, getAliases, getAUID, getComment, getDescription, getIdentification, getName, getSymbol, getWeakTargetReference, hashCode, initializeMetaDefinitionIdentification, initializeMetaDefinitionName, setAAFNamesInUse, setAliases, setDescription, setIdentification, setName, setNamespace, setPrefix, setSymbol, toString`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

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

      `getSymbol`

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

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

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

      `getWeakTargetReference`

    - ### Methods inherited from interface tv.amwa.maj.io.xml.XMLSerializable

      `getComment`

- - ### Constructor Detail

    - #### PropertyDefinitionImpl

          public PropertyDefinitionImpl(AUID identification,
                                        @AAFString
                                        String name,
                                        String type,
                                        ClassDefinition memberOf,
                                        @Bool
                                        boolean isOptional)
                                 throws NullPointerException

      Creates and initializes a new property definition, which describes an allowed property of a `class definition`.

      It is not normally necessary to create property definitions directly as they are available through methods of `ClassDefinition`. To extend the AAF object model with user defined classes, the `MediaProperty` annotation can be used to automatically generate property definitions.

      Parameters:
        `identification` - Unique identifier for the new property definition.
        `name` - Display name of the new property definition.
        `type` - Property type for the new property definition.
        `memberOf` - Reference to the class this property is a member of, or `null` if this property is not associated with a class.
        `isOptional` - Can an object omit a value for this property?
      Throws:
        `NullPointerException` - One of the identification, name or type arguments is/are `null` and they are all required in this implementation.

  - ### Method Detail

    - #### initalizePropertyNameMap

          public static final void initalizePropertyNameMap()

    - #### getIsOptional

          @MediaProperty(uuid1=50397698,
                         uuid2=256,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,2},
                         definedName="IsOptional",
                         aliases="Optional",
                         typeName="Boolean",
                         optional=false,
                         uniqueIdentifier=false,
                         pid=12,
                         symbol="IsOptional")
          public boolean getIsOptional()

      Description copied from interface: `PropertyDefinition`

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

      Specified by:
        `getIsOptional` in interface `PropertyDefinition`
      Returns:
        Is the property optional?

    - #### setIsOptional

          @MediaPropertySetter(value="IsOptional")
          public void setIsOptional(boolean isOptional)

    - #### initializeIsOptional

          public static final boolean initializeIsOptional()

    - #### getIsUniqueIdentifier

          @MediaProperty(uuid1=100729095,
                         uuid2=1536,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,2},
                         definedName="IsUniqueIdentifier",
                         aliases={"UniqueIdentifier","IsUnique","Unique"},
                         typeName="Boolean",
                         optional=true,
                         uniqueIdentifier=false,
                         pid=14,
                         symbol="IsUniqueIdentifier")
          public boolean getIsUniqueIdentifier()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                   throws PropertyNotPresentException

      Description copied from interface: `PropertyDefinition`

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

      Specified by:
        `getIsUniqueIdentifier` in interface `PropertyDefinition`
      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.

    - #### setIsUniqueIdentifier

          @MediaPropertySetter(value="IsUniqueIdentifier")
          public void setIsUniqueIdentifier(Boolean isUniqueIdentifier)

    - #### getPropertyType

          @MediaProperty(uuid1=100729095,
                         uuid2=1024,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,2},
                         definedName="PropertyType",
                         aliases={"Type","PropertyDefinitionType"},
                         typeName="AUID",
                         optional=false,
                         uniqueIdentifier=false,
                         pid=11,
                         symbol="PropertyType")
          public AUID getPropertyType()

      Description copied from interface: `PropertyDefinition`

      Returns the identifier for the type of this property.

      Specified by:
        `getPropertyType` in interface `PropertyDefinition`
      Returns:
        Identifier for the type of this property.
      See Also:
        `PropertyDefinition.getTypeDefinition()`

    - #### setPropertyType

          @MediaPropertySetter(value="PropertyType")
          public void setPropertyType(AUID propertyType)
                                                                          throws NullPointerException

      Throws:
        `NullPointerException`

    - #### initializePropertyType

          public static final AUID initializePropertyType()

    - #### getTypeDefinition

          public TypeDefinition getTypeDefinition()

      Description copied from interface: `PropertyDefinition`

      Returns the property type of the defined property.

      Specified by:
        `getTypeDefinition` in interface `PropertyDefinition`
      Returns:
        Type definition for this property definition.
      See Also:
        `PropertyDefinition.getPropertyType()`

    - #### setTypeDefinition

          public void setTypeDefinition(TypeDefinition type)
                                 throws NullPointerException

      Throws:
        `NullPointerException`

    - #### getLocalIdentification

          @MediaProperty(uuid1=100729095,
                         uuid2=1280,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,2},
                         definedName="LocalIdentification",
                         typeName="UInt16",
                         optional=false,
                         uniqueIdentifier=false,
                         pid=13,
                         symbol="LocalIdentification")
          public short getLocalIdentification()

      Description copied from interface: `PropertyDefinition`

      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 `PropertyDefinition.getMemberOf()`. A value of zero indicates that no specified value is available and a unique tag should be generated dynamically on serialization.

      Specified by:
        `getLocalIdentification` in interface `PropertyDefinition`
      Returns:
        Local identification associated with this property definition.
      See Also:
        `PrimerPack.lookupLocalTag(AUID)`

    - #### setLocalIdentification

          @MediaPropertySetter(value="LocalIdentification")
          public void setLocalIdentification(Short localIdentification)

    - #### initializeLocalIdentification

          public static final short initializeLocalIdentification()

    - #### getMemberOf

          @MediaProperty(uuid1=100729095,
                         uuid2=8704,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,13},
                         definedName="MemberOf",
                         typeName="ClassDefinitionWeakReference",
                         optional=true,
                         uniqueIdentifier=false,
                         pid=43,
                         symbol="MemberOf",
                         description="Specifies the class in which this property may be present.")
          public ClassDefinition getMemberOf()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           throws PropertyNotPresentException

      Description copied from interface: `PropertyDefinition`

      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.

      Specified by:
        `getMemberOf` in interface `PropertyDefinition`
      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

          @MediaPropertySetter(value="MemberOf")
          public void setMemberOf(ClassDefinition memberOf)

      Description copied from interface: `PropertyDefinition`

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

      Specified by:
        `setMemberOf` in interface `PropertyDefinition`
      Parameters:
        `memberOf` - Class definition of the class that this property definition is associated with.

    - #### setPropertyValue

          public void setPropertyValue(MetadataObject metadataObject,
                                       PropertyValue propertyValue)
                                throws IllegalArgumentException

      Description copied from interface: `PropertyDefinition`

      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.

      Specified by:
        `setPropertyValue` in interface `PropertyDefinition`
      Parameters:
        `metadataObject` - Object to set this property for.
        `propertyValue` - Value to set for the property.
      Throws:
        `IllegalArgumentException` - An error occurred when trying to invole the underlying class' method.
      See Also:
        `PropertyDefinition.getPropertyValue(MetadataObject)`, `PropertyDefinition.getTypeDefinition()`, `TypeDefinition.createValue(Object)`

    - #### getPropertyValue

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

      Description copied from interface: `PropertyDefinition`

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

      Specified by:
        `getPropertyValue` in interface `PropertyDefinition`
      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.
        `IllegalArgumentException` - An error occurred when trying to invoke the underlying class' method.
        `PropertyNotPresentException` - The given property is optional, but not currently present in this instance of the class.
      See Also:
        `PropertyDefinition.setPropertyValue(MetadataObject, PropertyValue)`, `MediaEngine.getPropertyValue(MetadataObject, String)`

    - #### getMethodBag

          public MethodBag getMethodBag()

    - #### setAnnotatedGetter

          public void setAnnotatedGetter(Method getter)

    - #### isPropertyPresent

          public boolean isPropertyPresent(MetadataObject metadataObject)
                                    throws NullPointerException,
                                           IllegalPropertyException

      Description copied from interface: `PropertyDefinition`

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

      Specified by:
        `isPropertyPresent` in interface `PropertyDefinition`
      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`, `PropertyDefinition.omitOptionalProperty(MetadataObject)`, `MediaEngine.isPropertyPresent(MetadataObject, String)`

    - #### omitOptionalProperty

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

      Description copied from interface: `PropertyDefinition`

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

      Specified by:
        `omitOptionalProperty` in interface `PropertyDefinition`
      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)`, `PropertyDefinition.isPropertyPresent(MetadataObject)`

    - #### appendXMLChildren

          public void appendXMLChildren(Node parent)

      Description copied from interface: `XMLSerializable`

      Append extra child elements to the given parent node to serialize the value of an object to an XML fragment. Methods of the `XMLBuilder` class are provided to help with this process.

      Specified by:
        `appendXMLChildren` in interface `XMLSerializable`
      Overrides:
        `appendXMLChildren` in class `MetaDefinitionImpl`
      Parameters:
        `parent` - XML parent element to append child nodes to.

    - #### getNamespace

          public String getNamespace()

      Description copied from interface: `MetaDefinition`

      Returns the namespace in which the subject of this meta definition is defined.

      Specified by:
        `getNamespace` in interface `MetaDefinition`
      Overrides:
        `getNamespace` in class `MetaDefinitionImpl`
      Returns:
        Namespace in which the subject of this meta definition is defined.
      See Also:
        `MediaProperty.namespace()`, `MediaClass.namespace()`, `ExtensionScheme.getSchemeURI()`

    - #### getPrefix

          public String getPrefix()

      Description copied from interface: `MetaDefinition`

      Returns the namespace prefix to use when serializing a value of the subject of this meta definition to XML.

      Specified by:
        `getPrefix` in interface `MetaDefinition`
      Overrides:
        `getPrefix` in class `MetaDefinitionImpl`
      Returns:
        Namespace prefix to use when serializing a value of the subject of this meta definition to XML.
      See Also:
        `MediaProperty.prefix()`, `MediaClass.prefix()`

    - #### getIsXMLCDATA

          public boolean getIsXMLCDATA()

      Description copied from interface: `PropertyDefinition`

      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.

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

    - #### getIsXMLAttribute

          public boolean getIsXMLAttribute()

      Description copied from interface: `PropertyDefinition`

      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.

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

    - #### getFlattenXML

          public boolean getFlattenXML()

      Description copied from interface: `PropertyDefinition`

      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.

      Specified by:
        `getFlattenXML` in interface `PropertyDefinition`
      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()`

    - #### compareTo

          public int compareTo(PropertyDefinition o)

      Specified by:
        `compareTo` in interface `Comparable<PropertyDefinition>`

    - #### getWeight

          public int getWeight()

      Description copied from interface: `PropertyDefinition`

      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).

      Specified by:
        `getWeight` in interface `PropertyDefinition`
      Returns:
        Relative weight for ordering the property in a list.
      See Also:
        `MediaProperty.weight()`

    - #### nameToAAFName

          public String nameToAAFName(String name)

      Overrides:
        `nameToAAFName` in class `MetaDefinitionImpl`

    - #### appendMetadictXML

          public void appendMetadictXML(Node metadict,
                                        String namespace,
                                        String prefix)

      Description copied from interface: `MetaDefinition`

      Append an XML representation of this meta definition to the given XML node.

      Specified by:
        `appendMetadictXML` in interface `MetaDefinition`
      Overrides:
        `appendMetadictXML` in class `MetaDefinitionImpl`
      Parameters:
        `metadict` - Meta dictionary node to append a description of this node to.
      See Also:
        `CommonConstants.AAF_METADICT_NAMESPACE`

    - #### clone

          public PropertyDefinition clone()

      Description copied from interface: `MetaDefinition`

      Create a cloned copy of this meta definition.

      Specified by:
        `clone` in interface `MetaDefinition`
      Specified by:
        `clone` in interface `PropertyDefinition`
      Overrides:
        `clone` in class `MetaDefinitionImpl`
      Returns:
        Cloned copy of this meta definition.

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