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

tv.amwa.maj.meta

## Interface ClassDefinition

- All Superinterfaces:
    MetadataObject, MetaDefinition, WeakReferenceTarget
  All Known Implementing Classes:
    ClassDefinitionImpl

      public interface ClassDefinition
      extends MetaDefinition, WeakReferenceTarget

  Specifies the definition of an AAF class. The definition can be used to extend the class hierarchy defined in the AAF object specification v1.1 by specifying a new class or by defining additional optional properties for a defined class. The operations on a class definition include: managing the position of the class within the class hierarchy; accessing property definitions associated with the class.

  With the MAJ API, a Java class can be used to specify a class definition by using the `MediaClass` and `MediaProperty` annotations. In this way, AAF class specification data and the MAJ API implementation methods can be managed alongside one another.

  See Also:
    `MediaClass`, `Warehouse.lookForClass(Class)`, `Warehouse.lookForClass(String)`, `Warehouse.lookForClass(AUID)`, `TypeDefinitions.ClassDefinitionWeakReference`, `TypeDefinitions.ClassDefinitionStrongReference`, `TypeDefinitions.ClassDefinitionStrongReferenceSet`, `InterchangeObject.getObjectClass()`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `ClassDefinition` | `clone()` Create a cloned copy of this class definition.
    `int` | `countProperties(MetadataObject metadataObject)` Returns the number of properties currently present in the given metadata object, including all required properties.
    `int` | `countPropertyDefinitions()` Returns number of property definitions in this class.
    `MetadataObject` | `createInstance()` Creates an instance of this class and returns it, or `null` if the instantiation failed.
    `Set<PropertyDefinition>` | `getAllPropertyDefinitions()` Returns all AAF property definitions attached directly to the current class and its ancestors.
    `EmitXMLClassIDAs` | `getEmitXMLClassIDAs()` Determines how the identifier of the class should be serialized to XML.
    `Class<?>` | `getJavaImplementation()` Returns the Java class implementation associated with the defined class.
    `ClassDefinition` | `getParent()` Gets the Parent class for this class definition.
    `SortedMap<? extends PropertyDefinition,? extends PropertyValue>` | `getProperties(MetadataObject metadataObject)` Returns the set of properties of the given object, where each property contains its property definition and current value.
    `Set<? extends PropertyDefinition>` | `getPropertyDefinitions()` Returns the AAF property definitions attached directly to the current class.
    `String` | `getSymbol()` Returns the symbol name for this class, which is the same as its tag name in registered data XML.
    `PropertyDefinition` | `getUniqueIdentifierProperty()` Returns the property definition corresponding to this class' unique identifier.
    `PropertyValue` | `getUniqueIdentifierValue(MetadataObject metadataObject)` Returns the current value of the unique identifier for a value of a type defined by this class definition.
    `boolean` | `isConcrete()` Returns `true` if the defined class can be instantiated; returns `false` otherwise.
    `boolean` | `isRoot()` Returns `true` if the defined class is the base of the inheritance hierarchy; returns `false` otherwise.
    `boolean` | `isUniquelyIdentified()` Returns `true` if the defined class is uniquely identified, which means that it has a single property that is a unique identifier for any given instance.
    `PropertyDefinition` | `lookupPropertyDefinition(AUID propertyId)` Looks up and returns the property definition corresponding to the given AUID in the set of properties defined for this class.
    `PropertyDefinition` | `lookupPropertyDefinition(short propertyTag)` Looks up and returns the property definition corresponding to the given short tag in the set of all properties defined for this class.
    `PropertyDefinition` | `lookupPropertyDefinition(String propertyName)` Looks up and returns the property definition corresponding to the given name in the set of all properties defined for this class.
    `PropertyDefinition` | `registerNewPropertyDefinition(AUID identification, String name, String[] aliases, String symbol, String typeName, boolean isOptional, boolean isUniqueIdentifier, Short pid)` Creates a new property definition and registers it in this class definition.
    `PropertyDefinition` | `registerOptionalPropertyDefinition(AUID identification, String name, String[] aliases, String symbol, String typeName)` Creates a new property definition and registers it in this class definition.
    `void` | `setJavaImplementation(Class<?> javaImplementation)` Sets the Java class implementation associated with the defined class.

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

- - ### Method Detail

    - #### getPropertyDefinitions

          Set<? extends PropertyDefinition> getPropertyDefinitions()

      Returns the AAF property definitions attached directly to the current class.

      Returns:
        Shallow copy of the set of property definitions that define the properties for this class.
      See Also:
        `getAllPropertyDefinitions()`, `TypeDefinitions.PropertyDefinitionStrongReferenceSet`

    - #### getAllPropertyDefinitions

          Set<PropertyDefinition> getAllPropertyDefinitions()

      Returns all AAF property definitions attached directly to the current class and its ancestors.

      Returns:
        The set of property definitions that define the properties for this class and all of its ancestors.
      See Also:
        `getPropertyDefinitions()`, `getProperties(MetadataObject)`

    - #### countPropertyDefinitions

          @UInt32
          int countPropertyDefinitions()

      Returns number of property definitions in this class.

      Returns:
        Number of properties contained in this class definition.

    - #### registerNewPropertyDefinition

          PropertyDefinition registerNewPropertyDefinition(AUID identification,
                                                           @AAFString
                                                           String name,
                                                           String[] aliases,
                                                           @AAFString
                                                           String symbol,
                                                           String typeName,
                                                           boolean isOptional,
                                                           boolean isUniqueIdentifier,
                                                           Short pid)
                                                    throws NullPointerException,
                                                           ObjectAlreadyAttachedException,
                                                           AlreadyUniquelyIdentifiedException

      Creates a new property definition and registers it in this class definition. The new property definition is returned.

      Note that it is illegal to add mandatory properties to an existing (registered) class. This method will allow adding either optional or mandatory properties to a class, but they must be added to a class which has not yet been registered in the dictionary. If this class has already been registered, it is possible to add optional properties, but not through this method. Optional properties added to an existing (registered) class are not supported dynamically in the MAJ API.

      Parameters:
        `identification` - AUID to be used to identify this property.
        `name` - Name of the new property.
        `aliases` - A set of additional names that can be used to identify the property.
        `symbol` - Registered data symbol for the property.
        `typeName` - Name of the type of value represented by the new property.
        `isOptional` - True if new property is to be optional.
        `isUniqueIdentifier` - True if new property is to be the unique identifier of the class.
        `pid` - Short tag used to identify the property, or `null` if it is not known.
      Returns:
        The newly created property definition.
      Throws:
        `NullPointerException` - One of the name or type definition arguments is null.
        `ObjectAlreadyAttachedException` - A property with the given identifier has already been registered.
        `AlreadyUniquelyIdentifiedException` - This class already has a unique identifier property.
      See Also:
        `MetaDictionary.getClassDefinitions()`, `PropertyDefinition`, `registerOptionalPropertyDefinition(AUID, String, String[], String, String)`

    - #### registerOptionalPropertyDefinition

          PropertyDefinition registerOptionalPropertyDefinition(AUID identification,
                                                                @AAFString
                                                                String name,
                                                                String[] aliases,
                                                                @AAFString
                                                                String symbol,
                                                                String typeName)
                                                         throws NullPointerException,
                                                                ObjectAlreadyAttachedException

      Creates a new property definition and registers it in this class definition. The new property definition is returned.

      Note that it is illegal to add mandatory properties to an already existing (registered) class. It is assumed that this property is being added to a class which is already registered. If so, it must be optional and this method will declare it so. If it is wished to add a mandatory property, that may be done through the `registerNewPropertyDefinition()` method, but that must be called on a class which is not yet registered.

      Parameters:
        `identification` - AUID to be used to identify this property.
        `name` - Name of the new property.
        `aliases` - A set of additional names that can be used to identify the property.
        `symbol` - Registered data symbol for the property.
        `typeName` - Name of the type of value represented by the new property.
      Returns:
        Newly created property definition.
      Throws:
        `NullPointerException` - Name or typeDef argument is null.
        `ObjectAlreadyAttachedException` - The given property identifier has already been registered.
      See Also:
        `registerNewPropertyDefinition(AUID, String, String[], String, String, boolean, boolean, Short)`

    - #### lookupPropertyDefinition

          PropertyDefinition lookupPropertyDefinition(AUID propertyId)
                                               throws NullPointerException,
                                                      BadParameterException

      Looks up and returns the property definition corresponding to the given AUID in the set of properties defined for this class.

      Parameters:
        `propertyId` - AUID identifying the property to look up.
      Returns:
        Property definition with the given identifier.
      Throws:
        `NullPointerException` - The given property identifier is `null`.
        `BadParameterException` - The given property identifier is not registered as a property definition for this class.
      See Also:
        `lookupPropertyDefinition(String)`, `lookupPropertyDefinition(short)`, `getAllPropertyDefinitions()`, `TypeDefinitions.PropertyDefinitionWeakReference`

    - #### lookupPropertyDefinition

          PropertyDefinition lookupPropertyDefinition(String propertyName)
                                               throws NullPointerException,
                                                      BadParameterException

      Looks up and returns the property definition corresponding to the given name in the set of all properties defined for this class. The name may be either the property's defined name, symbol name or one of its aliases.

      Parameters:
        `propertyName` - String identifying the property to look up.
      Returns:
        Property definition with the given identifier.
      Throws:
        `NullPointerException` - The given property identifier is `null`.
        `BadParameterException` - The given property identifier is not registered as a property definition for this class.
      See Also:
        `lookupPropertyDefinition(AUID)`, `lookupPropertyDefinition(String)`, `getAllPropertyDefinitions()`

    - #### lookupPropertyDefinition

          PropertyDefinition lookupPropertyDefinition(short propertyTag)
                                               throws NullPointerException,
                                                      BadParameterException

      Looks up and returns the property definition corresponding to the given short tag in the set of all properties defined for this class.

      Note that not all properties have defined tags, also known as local identification, and tags can be generated automatically when required.

      Parameters:
        `propertyTag` - Short identifier for the property to look up.
      Returns:
        Property definition with the given identifier.
      Throws:
        `NullPointerException` - The given property identifier is `null`.
        `BadParameterException` - The given property identifier is not registered as a property definition for this class.
      See Also:
        `lookupPropertyDefinition(AUID)`, `lookupPropertyDefinition(String)`, `getAllPropertyDefinitions()`

    - #### getParent

          ClassDefinition getParent()

      Gets the Parent class for this class definition. If there is no parent then `null` is returned. The only classes which have no parent will be `InterchangeObject` and `MetaDefinition`. These classes return themselves as their own parents to indicate that they are the root of the type hierarchy.

      Returns:
        Parent class of this class definition, this class if it is the root of the class hierarchy or `null` if no parent class has been defined.

    - #### isConcrete

          @Bool
          boolean isConcrete()

      Returns `true` if the defined class can be instantiated; returns `false` otherwise. If the class is not concrete, then it is abstract and implemented by an abstract Java class in the MAJ API. Any object in an AAF file that belongs to an abstract class shall also belong to a concrete subclass of the abstract class.

      Returns:
        Can the defined class be instantiated?

    - #### isRoot

          @Bool
          boolean isRoot()

      Returns `true` if the defined class is the base of the inheritance hierarchy; returns `false` otherwise.

      Returns:
        Is this a root (base) class?

    - #### isUniquelyIdentified

          @Bool
          boolean isUniquelyIdentified()

      Returns `true` if the defined class is uniquely identified, which means that it has a single property that is a unique identifier for any given instance.

      Returns:
        Is this a uniquely identified class?
      See Also:
        `getUniqueIdentifierProperty()`, `PropertyDefinition.getIsUniqueIdentifier()`, `getUniqueIdentifierValue(MetadataObject)`

    - #### getUniqueIdentifierProperty

          PropertyDefinition getUniqueIdentifierProperty()

      Returns the property definition corresponding to this class' unique identifier.

      Returns:
        The unique identifier of this class definition, or `null` if the class does not have a unique identifier property definition.
      See Also:
        `isUniquelyIdentified()`, `PropertyDefinition.getIsUniqueIdentifier()`, `getUniqueIdentifierValue(MetadataObject)`

    - #### createInstance

          MetadataObject createInstance()

      Creates an instance of this class and returns it, or `null` if the instantiation failed. This method is not the recommended way of creating objects in the MAJ API as the values of the class will not be initialized to sensible values. To create implementations of the objects safely, use the make methods of the media engine instead.

      This method is provided for implementations of file reading mechanisms that need to create uninitialized objects before setting all required properties from the input stream.

      Returns:
        An instance object defined by this class definition, or `null` if the instantiation failed.
      See Also:
        `Forge.make(Class, Object...)`

    - #### getJavaImplementation

          Class<?> getJavaImplementation()
                                  throws PropertyNotPresentException

      Returns the Java class implementation associated with the defined class.

      Returns:
        Java class implementation associated with this AAF class definition.
      Throws:
        `PropertyNotPresentException` - The optional java implementation property is not present in this AAF class definition.
      See Also:
        `MediaClass`, `Warehouse.lookForClass(Class)`

    - #### setJavaImplementation

          void setJavaImplementation(Class<?> javaImplementation)

      Sets the Java class implementation associated with the defined class.

      Parameters:
        `javaImplementation` - Java class implementation associated with this AAF class definition.
      See Also:
        `MediaClass`, `Warehouse.lookForClass(Class)`

    - #### getProperties

          SortedMap<? extends PropertyDefinition,? extends PropertyValue> getProperties(MetadataObject metadataObject)
                                                                                 throws NullPointerException,
                                                                                        IllegalArgumentException

      Returns the set of properties of the given object, where each property contains its property definition and current value. The set contains both required properties and optional properties that are currently present.

      Parameters:
        `metadataObject` - Object of this class to retrieve the properties for.
      Returns:
        Iterator over the set of properties of this interchange object.
      Throws:
        `NullPointerException` - The metadata object is `null`.
        `IllegalArgumentException` - The metadata object is not an instance of this class.

    - #### countProperties

          @UInt32
          int countProperties(MetadataObject metadataObject)
                               throws NullPointerException,
                                      IllegalArgumentException

      Returns the number of properties currently present in the given metadata object, including all required properties.

      Parameters:
        `metadataObject` - Object of this class to count the number of present properties.
      Returns:
        Number of properties present for the given metadata object.
      Throws:
        `NullPointerException` - The metadata object is `null`.
        `IllegalArgumentException` - The metadata object is not an instance of this class.

    - #### getSymbol

          @AAFString
          String getSymbol()

      Returns the symbol name for this class, 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()`, `MediaClass.symbol()`, `Utilities.makeSymbol(String)`

    - #### getUniqueIdentifierValue

          PropertyValue getUniqueIdentifierValue(MetadataObject metadataObject)
                                          throws NullPointerException,
                                                 IllegalArgumentException

      Returns the current value of the unique identifier for a value of a type defined by this class definition. The class must have a unique identifier for this method to by successful.

      Parameters:
        `metadataObject` - Object to find the unique identifier for.
      Returns:
        Value of the unique identifier.
      Throws:
        `NullPointerException` - Cannot find the unique identifier for a `null` value.
        `IllegalArgumentException` - The given object does not have a unique identifier property.
      See Also:
        `isUniquelyIdentified()`, `getUniqueIdentifierProperty()`

    - #### getEmitXMLClassIDAs

          EmitXMLClassIDAs getEmitXMLClassIDAs()

      Determines how the identifier of the class should be serialized to XML. For more details, see the description of the emit XML class ID as enumeration.

      Returns:
        How should the identifier of the class should be serialized to XML?
      See Also:
        `MediaClass.emitXMLClassID()`, `CommonConstants.XMLClassIDAsAttributeName`

    - #### clone

          ClassDefinition clone()

      Create a cloned copy of this class definition.

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

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