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

tv.amwa.maj.meta

## Interface MetaDictionary

- All Superinterfaces:
    Cloneable, MetadataObject
  All Known Implementing Classes:
    MetaDictionaryImpl

      public interface MetaDictionary
      extends MetadataObject, Cloneable

  Specifies a container for meta definitions. Every AAF file has a dictionary within its preface and also contains a representation of a meta dictionary.

  In MAJ, the meta dictionary is primarily represented by the warehouse. This keeps a per-virtual machine record of all meta definitions that have been registered. MAJ meta dictionaries can be static or dynamic:

  - A static meta dictionary contains all meta definitions known within the current warehouses. Static is the default state for the meta dictionary and can be explicitly set using `makeStatic()`.
  - A dynamic meta dictionary contains only the meta definitions required for a given preface at the time the preface is provided. To turn the meta dictionary into a dynamic one, call `makeDynamic(tv.amwa.maj.model.Preface)`.
  See Also:
    `Dictionary`, `MetaDefinition`, `Warehouse.lookForClass(String)`, `Warehouse.lookForType(String)`, `Preface`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `MetaDictionary` | `clone()` Create a cloned copy of this meta dictionary.
    `int` | `countClassDefinitions()` Returns the number of class definitions contained in this dictionary.
    `int` | `countOpaqueTypeDefinitions()` Returns the number of opaque type definitions in the dictionary.
    `int` | `countTypeDefinitions()` Returns the number of type definitions contained in the dictionary.
    `void` | `createForwardClassReference(AUID classId)` Creates a forward class reference that is used to allow a class definition to be referenced before it has had its full definition stored into this dictionary.
    `InterchangeObject` | `createInstance(AUID identification)` Deprecated. Use the `Forge.make(Class, Object...)` or equivalent instead.
    `MetaDefinition` | `createMetaInstance(AUID identification)` Deprecated. Use the `Forge.make(Class, Object...)` or equivalent instead.
    `Set<? extends ClassDefinition>` | `getClassDefinitions()` Returns the set of all class definitions in this dictionary.
    `boolean` | `getIsDynamic()` Is this meta dictionary dynamic? A dynamic meta dictionary represents only the meta definitions required to represent a given preface at a specific point in time.
    `Set<? extends TypeDefinition>` | `getOpaqueTypeDefinitions()` Return the set of all registered opaque type definitions in the dictionary.
    `Set<? extends TypeDefinition>` | `getTypeDefinitions()` Returns the set of all type definitions contained within this dictionary.
    `boolean` | `hasForwardClassReference(AUID classId)` Returns `true` if the given class identification is a forward reference registered with this dictionary.
    `ClassDefinition` | `lookupClassDefinition(AUID identification)` Returns the class definition with the given identifier that is contained in this dictionary.
    `TypeDefinition` | `lookupOpaqueTypeDefinition(AUID typeId)` Return the opaque type definition with the given id.
    `TypeDefinition` | `lookupTypeDefinition(AUID identification)` Return the type definition with the given identifier that is contained within this dictionary.
    `void` | `makeDynamic(Preface preface)` Turn this meta dictionary from static to dynamic and/or update the meta definitions to represent those required to represent the given preface.
    `void` | `makeStatic()` Turn this meta dictionary into a static meta dictionary, which is the default state.
    `void` | `registerClassDefinition(ClassDefinition classDefinition)` Add a class definition to those contained in this dictionary.
    `void` | `registerOpaqueTypeDefinition(TypeDefinition typeDef)` Add the opaque type definition to the dictionary.
    `void` | `registerTypeDefinition(TypeDefinition typeDefinition)` Add a type definition to those contained in this dictionary.

- - ### Method Detail

    - #### createInstance

          InterchangeObject createInstance(AUID identification)
                                    throws NullPointerException,
                                           IllegalArgumentException

      Deprecated. Use the `Forge.make(Class, Object...)` or equivalent instead.

      Creates a single uninitialized AAF object of the class associated with a specified interchange object class identifier.

      This method is a factory for creating objects found within the body of an AAF file. In MAJ, the equivalent functionality is provided through the factory provided on the media engine.

      Parameters:
        `identification` - Class identifier (id) of the stored object. This is the corresponding SMPTE identifier (as a GUID) for all predefined built-in classes or registered extension classes.
      Returns:
        Object that is an instance of the specified class and implements the interchange object interface.
      Throws:
        `NullPointerException` - Cannot create an instance from a `null` value.
        `IllegalArgumentException` - The given identifier is not known or is not for an object of interchange type.

    - #### createMetaInstance

          MetaDefinition createMetaInstance(AUID identification)
                                     throws NotImplementedException

      Deprecated. Use the `Forge.make(Class, Object...)` or equivalent instead.

      Creates a single uninitialized AAF meta definition (class or type) associated with a specified class identifier.

      This method is a factory for creating objects used to describe the meta dictionary of an AAF file. In MAJ, the equivalent functionality is provided through the factory provided on the media engine.

      Parameters:
        `identification` - Identifier (id) of a class or type definition. This is the corresponding SMPTE identifier (as a GUID) for all predefined built-in definitions or registered extensions.
      Returns:
        Instantiated metaclass.
      Throws:
        `NullPointerException` - Cannot create a meta instance for a `null` value.
        `IllegalArgumentException` - The given identifier is not known or is not for a meta definition.
        `NotImplementedException`

    - #### registerClassDefinition

          void registerClassDefinition(ClassDefinition classDefinition)
                                throws InvalidParameterException,
                                       NullPointerException

      Add a class definition to those contained in this dictionary.

      Parameters:
        `classDefinition` - Class definition to add.
      Throws:
        `InvalidParameterException` - A class definition with the same identifier is already contained in this dictionary.
        `NullPointerException` - The given class definition is `null`.
      See Also:
        `Warehouse.lookForClass(Class)`, `Warehouse.lookForClass(String)`

    - #### lookupClassDefinition

          ClassDefinition lookupClassDefinition(AUID identification)
                                         throws NullPointerException,
                                                InvalidParameterException

      Returns the class definition with the given identifier that is contained in this dictionary.

      Parameters:
        `identification` - Unique identifier for a class contained in this dictionary.
      Returns:
        Class definition with the given identification that is contained in this dictionary.
      Throws:
        `NullPointerException` - Argument is null.
        `InvalidParameterException` - The given class identifier does not match a class definition stored in this dictionary.
      See Also:
        `Warehouse.lookForClass(Class)`, `MediaClass`

    - #### getClassDefinitions

          Set<? extends ClassDefinition> getClassDefinitions()

      Returns the set of all class definitions in this dictionary.

      Returns:
        Shallow copy of the set of all class definitions contained in this dictionary.

    - #### countClassDefinitions

          @UInt32
          int countClassDefinitions()

      Returns the number of class definitions contained in this dictionary.

      Returns:
        Number of class definitions contained in this dictionary.

    - #### createForwardClassReference

          void createForwardClassReference(AUID classId)
                                    throws InvalidParameterException

      Creates a forward class reference that is used to allow a class definition to be referenced before it has had its full definition stored into this dictionary.

      Parameters:
        `classId` - Unique class identifier for the forward reference.
      Throws:
        `InvalidParameterException` - The given ID represents an existing forward class reference or a class definition that has already been successfully registered.

    - #### hasForwardClassReference

          @Bool
          boolean hasForwardClassReference(AUID classId)
                                          throws InvalidParameterException

      Returns `true` if the given class identification is a forward reference registered with this dictionary.

      Parameters:
        `classId` - Unique class identifier.
      Returns:
        Has the class got a forward reference in this dictionary?
      Throws:
        `InvalidParameterException` - The given ID is not recognized as a class definition id.

    - #### registerTypeDefinition

          void registerTypeDefinition(TypeDefinition typeDefinition)
                               throws NullPointerException,
                                      InvalidParameterException

      Add a type definition to those contained in this dictionary.

      Parameters:
        `typeDefinition` - Type definition to add to this dictionary.
      Throws:
        `NullPointerException` - The given type definition is `null`.
        `InvalidParameterException` - The given type has an id that matches the id of a type definition already contained in the dictionary.
      See Also:
        `Warehouse.lookForType(String)`, `Warehouse.lookForType(AUID)`, `Warehouse.registerTypes(Class, String, String)`, `Warehouse.register(TypeDefinition, String, String)`

    - #### lookupTypeDefinition

          TypeDefinition lookupTypeDefinition(AUID identification)
                                       throws NullPointerException,
                                              InvalidParameterException

      Return the type definition with the given identifier that is contained within this dictionary.

      Parameters:
        `identification` - Unique identifier for the type definition contained in this dictionary.
      Returns:
        Type definition in this dictionary with the given type id.
      Throws:
        `NullPointerException` - The given type identifier is `null`.
        `InvalidParameterException` - The given identifier does not match that of a type definition contained in this dictionary.

    - #### getTypeDefinitions

          Set<? extends TypeDefinition> getTypeDefinitions()

      Returns the set of all type definitions contained within this dictionary.

      Returns:
        Shallow copy of the set of type definitions contained in this dictionary.

    - #### countTypeDefinitions

          @UInt32
          int countTypeDefinitions()

      Returns the number of type definitions contained in the dictionary.

      Returns:
        Number of type definitions in this dictionary.

    - #### registerOpaqueTypeDefinition

          void registerOpaqueTypeDefinition(TypeDefinition typeDef)
                                     throws NullPointerException,
                                            InvalidParameterException

      Add the opaque type definition to the dictionary.

      An opaque type definition defines a property type that has a value whose type is specified in each instance.

      Parameters:
        `typeDef` - Type definition object.
      Throws:
        `NullPointerException` - Argument is null.
        `InvalidParameterException` - The given type has already been registered.

    - #### lookupOpaqueTypeDefinition

          TypeDefinition lookupOpaqueTypeDefinition(AUID typeId)
                                             throws NullPointerException,
                                                    InvalidParameterException

      Return the opaque type definition with the given id.

      Parameters:
        `typeId` - Unique type ID.
      Returns:
        Corresponding type definition.
      Throws:
        `NullPointerException` - Argument is null.
        `InvalidParameterException` - The given ID is not recognized as a type definition ID.

    - #### getOpaqueTypeDefinitions

          Set<? extends TypeDefinition> getOpaqueTypeDefinitions()

      Return the set of all registered opaque type definitions in the dictionary.

      Returns:
        Iterator over the set of all registered opaque type definitions.

    - #### countOpaqueTypeDefinitions

          @UInt32
          int countOpaqueTypeDefinitions()

      Returns the number of opaque type definitions in the dictionary.

      Returns:
        Number of opaque type definitions.

    - #### getIsDynamic

          boolean getIsDynamic()

      Is this meta dictionary dynamic? A dynamic meta dictionary represents only the meta definitions required to represent a given preface at a specific point in time. Otherwise, the meta dictionary is static and represents all meta definitions known to the current virtual machine.

      Returns:
        Is this meta dictionary dynamic?
      See Also:
        `makeStatic()`, `makeDynamic(Preface)`

    - #### makeDynamic

          void makeDynamic(Preface preface)
                    throws NullPointerException

      Turn this meta dictionary from static to dynamic and/or update the meta definitions to represent those required to represent the given preface.

      Parameters:
        `preface` - Preface to compute the meta dictionary for.
      Throws:
        `NullPointerException` - Cannot make a dynamic meta dictionary from a `null` value.
      See Also:
        `getIsDynamic()`, `makeStatic()`

    - #### makeStatic

          void makeStatic()

      Turn this meta dictionary into a static meta dictionary, which is the default state. In this state, the meta dictionary holds all meta definitions known to the current virtual machine.

      See Also:
        `getIsDynamic()`, `makeDynamic(Preface)`

    - #### clone

          MetaDictionary clone()

      Create a cloned copy of this meta dictionary.

      Returns:
        Cloned copy of this meta dictionary.

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