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

tv.amwa.maj.model

## Interface ApplicationObject

- All Superinterfaces:
    InterchangeObject, MediaEntity, MetadataObject
  All Known Subinterfaces:
    ApplicationPluginObject, ApplicationReferencedObject
  All Known Implementing Classes:
    ApplicationObjectImpl, ApplicationPluginObjectImpl, ApplicationReferencedObjectImpl

      public interface ApplicationObject
      extends InterchangeObject

  Common properties of application plugin objects and application referenced objects. These classes provide the mechanism to decorate interchange objects with application-specific extension metadata.

  See Also:
    `ExtensionScheme`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearExtensionProperties()` Clear all extension properties from this application object, effectively omitting them all.
    `ApplicationObject` | `clone()` Create a cloned copy of this application object.
    `int` | `countExtensionProperties()` Returns the number of extension properties that are present for this application object.
    `ClassDefinition` | `getBaseClass()` Returns the class identifier of the immediate superclass that this object extends.
    `PropertyValue` | `getExtensionProperty(AUID propertyID)` Get the value of an extension property by its property identifier.
    `PropertyValue` | `getExtensionProperty(String propertyName)` Get the value of an extension property by its property name.
    `Set<AUID>` | `getExtensionPropertyIDs()` Returns the set of extension property identifiers for present properties of this application object.
    `SortedMap<? extends PropertyDefinition,? extends PropertyValue>` | `getProperties()` Creates a map of all present property definitions of this application object and their current values.
    `boolean` | `isExtensionPropertyPresent(AUID propertyID)` Determines whether the given property identifier is for a present property of the application object.
    `boolean` | `isExtensionPropertyPresent(String propertyName)` Determines whether the given property name is for a present property of the application object.
    `void` | `putExtensionProperty(AUID propertyID, PropertyValue propertyValue)` Put an extension property value into this application object by property identifier, either creating the property the property and making it present, or updating its value.
    `void` | `putExtensionProperty(String propertyName, PropertyValue propertyValue)` Put an extension property value into this application object by property name, either creating the property the property and making it present, or updating its value.
    `void` | `setBaseClass(ClassDefinition baseClass)` Sets the class identifier of the immediate superclass that this object extends.

    - ### Methods inherited from interface tv.amwa.maj.model.InterchangeObject

      `addApplicationPlugin, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getGeneration, getLinkedGenerationID, getObjectClass, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setObjectClass, toString`

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

      `getPersistentID, setPersistentIndex`

- - ### Method Detail

    - #### getBaseClass

          ClassDefinition getBaseClass()
                                throws PropertyNotPresentException

      Returns the class identifier of the immediate superclass that this object extends. This is an optional property.

      Returns:
        Class identifier of the immediate superclass that this object extends.
      Throws:
        `PropertyNotPresentException` - The optional base class property is not present for this application object.
      See Also:
        `InterchangeObject.getObjectClass()`

    - #### setBaseClass

          void setBaseClass(ClassDefinition baseClass)

      Sets the class identifier of the immediate superclass that this object extends. Set this optional property to `null` to omit it.

      Parameters:
        `baseClass` - Class identifier of the immediate superclass that this object extends.
      See Also:
        `InterchangeObject.setObjectClass(ClassDefinition)`

    - #### putExtensionProperty

          void putExtensionProperty(AUID propertyID,
                                    PropertyValue propertyValue)
                             throws IllegalArgumentException,
                                    NullPointerException,
                                    IllegalPropertyValueException

      Put an extension property value into this application object by property identifier, either creating the property the property and making it present, or updating its value. The property should be within the context of the defined extension scheme.

      Note that the property value cannot itself be `null` but the value it wraps may be `null`, depending on the type and property definition. Property values can be created with the `TypeDefinition.createValue(Object)` method.

      Parameters:
        `propertyID` - Identifier of the property to add or update.
        `propertyValue` - Value of the property to update.
      Throws:
        `IllegalArgumentException` - The given property identifier is not found within an appropriate context.
        `NullPointerException` - One or both of the property identifier or value is/are `null`.
        `IllegalPropertyValueException` - The given property value does not match the type defined for the property.
      See Also:
        `putExtensionProperty(String, PropertyValue)`, `getExtensionProperty(AUID)`

    - #### putExtensionProperty

          void putExtensionProperty(String propertyName,
                                    PropertyValue propertyValue)
                             throws IllegalArgumentException,
                                    NullPointerException,
                                    IllegalPropertyValueException

      Put an extension property value into this application object by property name, either creating the property the property and making it present, or updating its value. The property should be within the context of the defined extension scheme.

      Note that the property value cannot itself be `null` but the value it wraps may be `null`, depending on the type and property definition. Property values can be created with the `TypeDefinition.createValue(Object)` method.

      Parameters:
        `propertyName` - Identifier of the property to add or update.
        `propertyValue` - Value of the property to update.
      Throws:
        `IllegalArgumentException` - The given property identifier is not known in the extension scheme.
        `NullPointerException` - One or both of the property identifier or value is/are `null`.
        `IllegalPropertyValueException` - The given property value does not match the type defined for the property.
      See Also:
        `putExtensionProperty(AUID, PropertyValue)`, `getExtensionProperty(String)`

    - #### getExtensionProperty

          PropertyValue getExtensionProperty(AUID propertyID)
                                      throws NullPointerException,
                                             PropertyNotPresentException,
                                             IllegalArgumentException

      Get the value of an extension property by its property identifier.

      Parameters:
        `propertyID` - Identifier of the extension property to retrieve the value of.
      Returns:
        Value of the extension property with the given identifier.
      Throws:
        `NullPointerException` - Cannot retrieve an extension property using a `null` identifier.
        `PropertyNotPresentException` - The given property identifier is not present for this application object.
        `IllegalArgumentException` - The given property identifier is not known in the extension scheme.
      See Also:
        `getExtensionProperty(String)`, `putExtensionProperty(String, PropertyValue)`

    - #### getExtensionProperty

          PropertyValue getExtensionProperty(String propertyName)
                                      throws NullPointerException,
                                             PropertyNotPresentException,
                                             IllegalArgumentException

      Get the value of an extension property by its property name.

      Parameters:
        `propertyName` - Name of the extension property to retrieve the value of.
      Returns:
        Value of the extension property with the given identifier.
      Throws:
        `NullPointerException` - Cannot retrieve an extension property using a `null` name.
        `PropertyNotPresentException` - The given property name is not present for this application object.
        `IllegalArgumentException` - The given property identifier is not known in the extension scheme.
      See Also:
        `getExtensionProperty(AUID)`, `putExtensionProperty(String, PropertyValue)`

    - #### isExtensionPropertyPresent

          boolean isExtensionPropertyPresent(AUID propertyID)
                                      throws NullPointerException,
                                             IllegalArgumentException

      Determines whether the given property identifier is for a present property of the application object. A property is present when it exists in the extension properties and its value is not `null`.

      Parameters:
        `propertyID` - Property identifier to check if the property is present.
      Returns:
        Is the property present for this application object?
      Throws:
        `NullPointerException` - Cannot check for the presence of a property using a `null` identifier.
        `IllegalArgumentException` - The given property identifier does not match one known in the associated extension scheme.
      See Also:
        `isExtensionPropertyPresent(String)`, `getExtensionProperty(AUID)`

    - #### isExtensionPropertyPresent

          boolean isExtensionPropertyPresent(String propertyName)
                                      throws NullPointerException,
                                             IllegalArgumentException

      Determines whether the given property name is for a present property of the application object. A property is present when it exists in the extension properties and its value is not `null`.

      Parameters:
        `propertyName` - Property identifier to check if the property is present.
      Returns:
        Is the property present for this application object?
      Throws:
        `NullPointerException` - Cannot check for the presence of a property using a `null` identifier.
        `IllegalArgumentException` - The given property identifier does not match one known in the associated extension scheme.
      See Also:
        `isExtensionPropertyPresent(AUID)`, `getExtensionProperty(String)`

    - #### countExtensionProperties

          int countExtensionProperties()

      Returns the number of extension properties that are present for this application object.

      Returns:
        Number of extension properties that are present for this application object.

    - #### clearExtensionProperties

          void clearExtensionProperties()

      Clear all extension properties from this application object, effectively omitting them all.

    - #### getExtensionPropertyIDs

          Set<AUID> getExtensionPropertyIDs()

      Returns the set of extension property identifiers for present properties of this application object. This set can be used to iterate through all of the property values with `getExtensionProperty(AUID)`.

      Returns:
        Set of property identifiers for present properties of this application object.

    - #### getProperties

          SortedMap<? extends PropertyDefinition,? extends PropertyValue> getProperties()

      Creates a map of all present property definitions of this application object and their current values.

      Returns:
        All present property definitions of this object mapped to their values.

    - #### clone

          ApplicationObject clone()

      Create a cloned copy of this application object.

      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Returns:
        Cloned copy of this application object.

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