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

tv.amwa.maj.model

## Interface Preface

- All Superinterfaces:
    InterchangeObject, MediaEntity, MetadataObject
  All Known Subinterfaces:
    QPreface
  All Known Implementing Classes:
    PrefaceImpl

      public interface Preface
      extends InterchangeObject

  Specifies file-wide information and indexes. An AAF file shall have exactly one preface object.

  When a preface is created, the contained dictionary object is automatically created.

  Note that the preface of an AAF file was preciously known as the header.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `OBJECTMODELVERSION_DEFAULT` Default value for the object model version property of a preface object which is 1.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addApplicationScheme(AUID applicationSchemeID)` Adds the identifier of an application metadata scheme to the set of schemes used in this file.
    `void` | `addDescriptiveScheme(AUID descriptiveSchemeID)` Adds the given descriptive metadata scheme identifier to the set of schemes of this preface, which identify the descriptive metadata schemes used in the file.
    `void` | `addEssenceContainer(AUID essenceContainerID)` Adds an essence container to the set of essence containers identifiers of this preface, which identify the internal essence containers used in the file.
    `void` | `addEssenceData(EssenceData essenceData)` Adds an essence data item to the content storage of this preface.
    `void` | `addPackage(Package packageToAdd)` Adds a package to the content storage of this preface.
    `void` | `appendIdentification(Identification identification)` Appends the given identification to the list of identifications of this preface, which each identify an application that created or modified the file.
    `void` | `clearApplicationSchemes()` Remove all application schemes from this preface, omitting this optional property.
    `void` | `clearDescriptiveSchemes()` Remove all descriptive schemes from this preface, omitting this optional property.
    `void` | `clearEssenceContainers()` Remove all essence containers from this preface, omitting this optional property.
    `Preface` | `clone()` Create a cloned copy of this preface.
    `int` | `countApplicationSchemes()` Returns the number of application metadata schemes recorded in the preface for this file.
    `int` | `countDescriptiveSchemes()` Returns the total number of descriptive metadata schemes present for this preface, which identify the descriptive metadata schemes used in the file.
    `int` | `countEssenceContainers()` Returns the total number of essence containers of this preface, which identify the internal essence containers used in the file.
    `int` | `countEssenceData()` Returns the total number of essence data items stored in the content storage of this preface.
    `int` | `countIdentifications()` Returns the number of identifications in the preface, which each identify an application that created or modified the file.
    `int` | `countPackages(PackageKind packageKind)` Returns the number of matches for the given package kind within the content storage of this preface.
    `Set<? extends EssenceData>` | `enumEssenceData()` Returns a set of all essence data stored in the content storage of this preface.
    `Set<AUID>` | `getApplicationSchemes()` Returns the set of identifiers for application metadata schemes used in the file.
    `ByteOrder` | `getByteOrder()` Returns the byte order of the file this preface was read from.
    `ContentStorage` | `getContentStorageObject()` Returns the content storage of this preface.
    `Set<AUID>` | `getDescriptiveSchemes()` Returns the set of descriptive schemes of this preface, which identify the descriptive metadata schemes used in the file.
    `Dictionary` | `getDictionaries()` Returns the dictionary of this preface, which contains all the definitions of the file.
    `Set<AUID>` | `getEssenceContainers()` Returns the set of essence containers of this preface, which identify the internal essence containers used in the file.
    `Set<? extends EssenceData>` | `getEssenceData()` Returns all the essence data objects from the content storage of this preface.
    `Set<? extends EssenceData>` | `getEssenceData(CriteriaType mediaCriteria)` Returns a set of essence data from the content storage of this preface that matches the given media criteria.
    `TimeStamp` | `getFileLastModified()` Return the last modified time stamp of this preface, which specifies the time and date that this file was last modified.
    `VersionType` | `getFormatVersion()` Return the file version property of the preface.
    `Identification` | `getIdentificationAt(int index)` Retrieves the identification at the given index through the list of identifications of this preface, which each identify an application that created or modified the file.
    `List<? extends Identification>` | `getIdentifications()` Returns the list of identifications contained within this preface, which each identify an application that created or modified the file.
    `Identification` | `getLastIdentification()` Returns the identification of the last application that modified the file.
    `ProductVersion` | `getMajApiVersion()` Return the version of the MAJ API currently running on this machine, which implements these interfaces.
    `int` | `getObjectModelVersion()` Returns the version of the persistent storage format for objects of this preface.
    `AUID` | `getOperationalPattern()` Returns the identifier of the MXF operational pattern or AAF protocol that the file of this preface complies with.
    `Set<? extends Package>` | `getPackages()` Returns all the packages stored in the content storage of this preface.
    `Set<? extends Package>` | `getPackages(SearchCriteria searchCriteria)` Returns a set of packages stored in the content storage of this preface that match the given `search criteria`.
    `Package` | `getPrimaryPackage()` Returns the primary package identifier for the file of this preface, which specifies the package that an MXF application treats as the default or primary package.
    `boolean` | `isApplicationSchemePresent(AUID applicationSchemeID)` Returns `true` if the given identifier matches one of the application metadata scheme stated to be in the file.
    `boolean` | `isDescriptiveSchemePresent(AUID descriptiveSchemeId)` Returns `true` if the descriptive metadata scheme with the given identifier is in set of schemes of this preface; otherwise `false`.
    `boolean` | `isEssenceContainerPresent(AUID essenceContainerId)` Returns `true` if the essence containers with the given identifier is present for this preface; otherwise `false`.
    `boolean` | `isEssenceDataPresent(PackageID filePackageID)` Returns `true` if essence data identified by the given package id is present in the content storage of this preface.
    `EssenceData` | `lookupEssenceData(PackageID packageID)` Looks up and returns the essence data that matches the given package id from the content storage of this preface.
    `Identification` | `lookupIdentification(AUID generation)` Returns the identification that matches the given generation identifier from the list of identifications of applications that created or modified the file of this preface.
    `Package` | `lookupPackage(PackageID packageID)` Returns the package that matches the given package id stored in the content storage of this preface.
    `void` | `removeApplicationScheme(AUID applicationSchemeID)` Remove an application metadata scheme from the set of application schemes of this file.
    `void` | `removeDescriptiveScheme(AUID descriptiveSchemeID)` Removes the given descriptive metadata scheme identifier from the set of schemes of this preface, which identify the descriptive metadata schemes used in the file.
    `void` | `removeEssenceData(EssenceData essenceData)` Removes the given essence data item from the content storage of this preface.
    `void` | `removePackage(Package packageToRemove)` Removes the given package from the content storage of this preface.
    `void` | `setFileLastModified(TimeStamp fileLastModified)` Set the last modified time stamp of this preface, which specifies the time and date that this file was last modified.
    `void` | `setOperationalPattern(AUID operationalPatternId)` Sets the MXF operational pattern or AAF protocol that the file of this preface complies with.
    `void` | `setPrimaryPackage(Package primaryPackageID)` Sets the primary package identifier for the file of the preface, which specifies the package that an MXF application treats as the default or primary package.
    `boolean` | `updateDictionaries()` Iterate through the content storage packages and make sure the dictionary contains all the referenced definitions, adding any missing definitions.
    `void` | `updateEssenceContainers()` Ensures that the contents of the essence containers property is in sync with the file's metadata.

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

- - ### Field Detail

    - #### OBJECTMODELVERSION_DEFAULT

          static final int OBJECTMODELVERSION_DEFAULT

      Default value for the object model version property of a preface object which is 1. This proeprty is automatically maintained and so has no get or set method.

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### lookupPackage

          Package lookupPackage(PackageID packageID)
                         throws NullPointerException,
                                PackageNotFoundException

      Returns the package that matches the given package id stored in the content storage of this preface.

      Parameters:
        `packageID` - The identifier of the package to look up in the content storage of this preface.
      Returns:
        The package from the storage with the matching identifier.
      Throws:
        `NullPointerException` - The given package identifier is `null`.
        `PackageNotFoundException` - A package with the given identifier was not found in the content storage of this preface.
      See Also:
        `getContentStorageObject()`, `ContentStorage.lookupPackage(PackageID)`

    - #### countPackages

          @UInt32
          int countPackages(PackageKind packageKind)

      Returns the number of matches for the given package kind within the content storage of this preface. Use `PackageKind.AllPackages` to count the total number of packages.

      Parameters:
        `packageKind` - The kind of packages to count.
      Returns:
        Total number of packages matching the given package kind in the content storage of this preface.
      See Also:
        `getContentStorageObject()`, `ContentStorage.countPackages(PackageKind)`

    - #### getPackages

          Set<? extends Package> getPackages(SearchCriteria searchCriteria)

      Returns a set of packages stored in the content storage of this preface that match the given `search criteria`. If the search criteria is `null`, all packages are returned.

      Parameters:
        `searchCriteria` - Search criteria to use to filter the set of packages returned.
      Returns:
        Set of packages matching the search criteria, or the set of all packages if the search criteria was `null`. The set does not clone packages it contains.
      See Also:
        `getContentStorageObject()`, `getPackages()`, `ContentStorage.getPackages(SearchCriteria)`, `ContentStorage.getPackages()`

    - #### getPackages

          Set<? extends Package> getPackages()

      Returns all the packages stored in the content storage of this preface.

      Returns:
        Set of all packages stored in the content storage of this preface.
      See Also:
        `getContentStorageObject()`, `getPackages(SearchCriteria)`, `ContentStorage.getPackages()`

    - #### addPackage

          void addPackage(Package packageToAdd)
                   throws NullPointerException,
                          DuplicatePackageIDException

      Adds a package to the content storage of this preface.

      Parameters:
        `packageToAdd` - Package to add to the content storage of this preface.
      Throws:
        `NullPointerException` - The given package is `null`.
        `DuplicatePackageIDException` - A package with the same package id is already contained in the content storage of this preface.
      See Also:
        `getContentStorageObject()`, `ContentStorage.addPackage(Package)`

    - #### removePackage

          void removePackage(Package packageToRemove)
                      throws NullPointerException,
                             PackageNotFoundException

      Removes the given package from the content storage of this preface.

      Parameters:
        `packageToRemove` - Package to remove from the preface.
      Throws:
        `NullPointerException` - The given package to remove is `null`.
        `PackageNotFoundException` - The given package is not contained in the content storage of this preface.
      See Also:
        `getContentStorageObject()`, `ContentStorage.removePackage(Package)`

    - #### countEssenceData

          @UInt32
          int countEssenceData()

      Returns the total number of essence data items stored in the content storage of this preface.

      Returns:
        Total number of essence data items stored in the content storage of this preface.
      See Also:
        `getContentStorageObject()`, `ContentStorage.countEssenceDataObjects()`

    - #### isEssenceDataPresent

          @Bool
          boolean isEssenceDataPresent(PackageID filePackageID)
                                      throws NullPointerException,
                                             InvalidParameterException

      Returns `true` if essence data identified by the given package id is present in the content storage of this preface.

      Parameters:
        `filePackageID` - Identifier of a file package that may be present in the content storage of this preface.
      Returns:
        Does the given package id match that of an essence data item stored in thie content storage of this preface?
      Throws:
        `NullPointerException` - The given package id is `null`.
        `InvalidParameterException` - The given file package id does not identify a file source package.
      See Also:
        `getContentStorageObject()`, `ContentStorage.isEssenceDataPresent(PackageID)`

    - #### enumEssenceData

          Set<? extends EssenceData> enumEssenceData()

      Returns a set of all essence data stored in the content storage of this preface.

      Returns:
        Shallow copy of the set of all essence data stored in the content storage of this preface.
      See Also:
        `getEssenceData(CriteriaType)`, `getContentStorageObject()`, `ContentStorage.enumEssenceDataObjects()`

    - #### getEssenceData

          Set<? extends EssenceData> getEssenceData(CriteriaType mediaCriteria)
                                             throws NullPointerException

      Returns a set of essence data from the content storage of this preface that matches the given media criteria. If the media criteria is CriteriaType.AnyRepresentation then all essence data that is stored in the content storage of this preface is included, producing the same result as calling `enumEssenceData()`.

      Parameters:
        `mediaCriteria` - Criteria for selecting essence data from storage.
      Returns:
        Set of essence data matching the criteria that is stored in the content storage of this preface. Note that the essence data items are not cloned.
      Throws:
        `NullPointerException`
      See Also:
        `getEssenceData()`, `enumEssenceData()`, `getContentStorageObject()`, `ContentStorage.getEssenceDataObjects(CriteriaType)`

    - #### getEssenceData

          Set<? extends EssenceData> getEssenceData()

      Returns all the essence data objects from the content storage of this preface.

      Returns:
        Set of all the essence data objects from the content storage of this preface.
      See Also:
        `enumEssenceData()`, `getEssenceData(CriteriaType)`, `ContentStorage.getEssenceDataObjects()`

    - #### addEssenceData

          void addEssenceData(EssenceData essenceData)
                       throws DuplicatePackageIDException,
                              NullPointerException

      Adds an essence data item to the content storage of this preface.

      Parameters:
        `essenceData` - Essence data to add to the content storage of this preface.
      Throws:
        `DuplicatePackageIDException` - Essence data with the same package id is already contained in the content storage of this preface.
        `NullPointerException` - The given essence data item is `null`.
      See Also:
        `getContentStorageObject()`, `ContentStorage.addEssenceDataObject(EssenceData)`

    - #### removeEssenceData

          void removeEssenceData(EssenceData essenceData)
                          throws NullPointerException,
                                 EssenceNotFoundException

      Removes the given essence data item from the content storage of this preface.

      Parameters:
        `essenceData` - Essence data to remove from the content storage of this preface.
      Throws:
        `NullPointerException` - The given essence data item is `null`.
        `EssenceNotFoundException` - The given essence data item is not contained in the content storage of this preface.
      See Also:
        `getContentStorageObject()`, `ContentStorage.removeEssenceDataObject(EssenceData)`

    - #### lookupEssenceData

          EssenceData lookupEssenceData(PackageID packageID)
                                 throws NullPointerException,
                                        PackageNotFoundException

      Looks up and returns the essence data that matches the given package id from the content storage of this preface.

      Parameters:
        `packageID` - Identifier for essence data stored in the content storage of this preface.
      Returns:
        Essence data stored in the content storage of this preface with the given package id.
      Throws:
        `NullPointerException` - The given package id is `null`.
        `PackageNotFoundException` - Essence data identified with the given package id is not stored in the content storage of the preface.
      See Also:
        `getContentStorageObject()`, `ContentStorage.lookupEssenceDataObject(PackageID)`

    - #### getDictionaries

          Dictionary getDictionaries()

      Returns the dictionary of this preface, which contains all the definitions of the file. The dictionary is automatically created when the preface object is created.

      Returns:
        AAF dictionary of the preface.
      See Also:
        `TypeDefinitions.DictionaryStrongReference`

    - #### getLastIdentification

          Identification getLastIdentification()

      Returns the identification of the last application that modified the file.

      Returns:
        Identification of last application that modified the file.

    - #### lookupIdentification

          Identification lookupIdentification(AUID generation)
                                       throws NullPointerException,
                                              ObjectNotFoundException

      Returns the identification that matches the given generation identifier from the list of identifications of applications that created or modified the file of this preface.

      Parameters:
        `generation` - Unique generation identifier to retrieve from the list of identifications of this preface.
      Returns:
        Identification with the given identifier from the list of identifications of this preface.
      Throws:
        `NullPointerException` - The given generation identifier is `null`.
        `ObjectNotFoundException` - An identification with the given identifier was not found in the list of identifications of this preface.

    - #### countIdentifications

          @UInt32
          int countIdentifications()

      Returns the number of identifications in the preface, which each identify an application that created or modified the file.

      Returns:
        Number of identifications in the list of identifications of this preface.

    - #### getIdentifications

          List<? extends Identification> getIdentifications()

      Returns the list of identifications contained within this preface, which each identify an application that created or modified the file.

      Returns:
        Shallow copy of the list of identifications in this preface.
      See Also:
        `TypeDefinitions.IdentificationStrongReferenceVector`

    - #### appendIdentification

          void appendIdentification(Identification identification)
                             throws NullPointerException

      Appends the given identification to the list of identifications of this preface, which each identify an application that created or modified the file. The identification at the end of the list should represent the most recent application to modify the file. This method does not attempt to identify duplicate identifications, so it will succeed even if an identical identification is already contained in the list.

      Parameters:
        `identification` - Identification to append to the list of identifications of this preface.
      Throws:
        `NullPointerException` - The given identification is `null`.

    - #### getIdentificationAt

          Identification getIdentificationAt(@UInt32
                                             int index)
                                      throws IndexOutOfBoundsException

      Retrieves the identification at the given index through the list of identifications of this preface, which each identify an application that created or modified the file.

      Parameters:
        `index` - 0-based index of the identification to retrieve from the list of identifications of this preface.
      Returns:
        Identification at the given index.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current list of identifications of this preface.

    - #### getMajApiVersion

          ProductVersion getMajApiVersion()

      Return the version of the MAJ API currently running on this machine, which implements these interfaces.

      Returns:
        MAJ API version.
      See Also:
        `getLastIdentification()`, `Identification.getRefImplVersion()`

    - #### getFormatVersion

          VersionType getFormatVersion()

      Return the file version property of the preface.

      Returns:
        File version.

    - #### getFileLastModified

          TimeStamp getFileLastModified()

      Return the last modified time stamp of this preface, which specifies the time and date that this file was last modified.

      Returns:
        Last modification time stamp.

    - #### setFileLastModified

          void setFileLastModified(TimeStamp fileLastModified)
                            throws NullPointerException

      Set the last modified time stamp of this preface, which specifies the time and date that this file was last modified. This value should match that of the `most recent identification`.

      Parameters:
        `fileLastModified` - Time stamp for the most recent modification of the file.
      Throws:
        `NullPointerException` - Cannot set the timestamp using a `null` value.
      See Also:
        `getLastIdentification()`

    - #### getContentStorageObject

          ContentStorage getContentStorageObject()

      Returns the content storage of this preface. This is the Content property of a preface.

      Returns:
        Content storage of this object.

    - #### getPrimaryPackage

          Package getPrimaryPackage()
                             throws PropertyNotPresentException

      Returns the primary package identifier for the file of this preface, which specifies the package that an MXF application treats as the default or primary package. This is an optional property.

      Returns:
        Primary package identifier for the file of this preface.
      Throws:
        `PropertyNotPresentException` - The optional primary package identifier is not present in the preface.
      See Also:
        `PackageID.getMaterial()`

    - #### setPrimaryPackage

          void setPrimaryPackage(Package primaryPackageID)

      Sets the primary package identifier for the file of the preface, which specifies the package that an MXF application treats as the default or primary package. Set this optional property to `null` to omit it.

      Parameters:
        `primaryPackageID` - Primary package identifier for the file of this preface.
      See Also:
        `PackageID.getMaterial()`

    - #### getOperationalPattern

          AUID getOperationalPattern()
                              throws PropertyNotPresentException

      Returns the identifier of the MXF operational pattern or AAF protocol that the file of this preface complies with. This is an optional property.

      Returns:
        Operational pattern that the file of this preface complies with.
      Throws:
        `PropertyNotPresentException` - Property is not present in the preface.
      See Also:
        `OperationalPatternConstant`

    - #### setOperationalPattern

          void setOperationalPattern(AUID operationalPatternId)
                              throws NullPointerException

      Sets the MXF operational pattern or AAF protocol that the file of this preface complies with. Set this optional property to `null` to omit it.

      Parameters:
        `operationalPatternId` - Operational pattern identifier for the preface.
      Throws:
        `NullPointerException` - The given operational pattern identifier is `null`.
      See Also:
        `OperationalPatternConstant`

    - #### updateEssenceContainers

          void updateEssenceContainers()

      Ensures that the contents of the essence containers property is in sync with the file's metadata. If this method succeeds, the essence containers property will contain identifiers of all container definitions referenced by `source packages` in the file of the preface.

      If the property isn't present it will be created. It is recommended that this method is called before any other of the methods affecting the essence containers can be called.

      See Also:
        `ContainerDefinition`

    - #### countEssenceContainers

          @UInt32
          int countEssenceContainers()
                                      throws PropertyNotPresentException

      Returns the total number of essence containers of this preface, which identify the internal essence containers used in the file.

      Returns:
        Total number of essence containers present in the file of the preface.
      Throws:
        `PropertyNotPresentException` - Essence containers are not present in the file of the preface.

    - #### clearEssenceContainers

          void clearEssenceContainers()

      Remove all essence containers from this preface, omitting this optional property.

      See Also:
        `getEssenceContainers()`, `countEssenceContainers()`

    - #### getEssenceContainers

          Set<AUID> getEssenceContainers()
                                  throws PropertyNotPresentException

      Returns the set of essence containers of this preface, which identify the internal essence containers used in the file. This is an optional property that is automatically maintained.

      Returns:
        Copy of the identifiers for the internal essence containers of this preface. The identifiers are cloned.
      Throws:
        `PropertyNotPresentException` - The optional set of essence containers is not present for this preface.
      See Also:
        `ContainerConstant`, `ContainerDefinition`

    - #### isEssenceContainerPresent

          @Bool
          boolean isEssenceContainerPresent(AUID essenceContainerId)
                                           throws NullPointerException

      Returns `true` if the essence containers with the given identifier is present for this preface; otherwise `false`. The set of essence containers identify the internal essence containers used in the file. The essence containers property of a preface is optional.

      Parameters:
        `essenceContainerId` - Identifier of the type of essence container to check for.
      Returns:
        Is the given essence container identifier in this preface?
      Throws:
        `NullPointerException` - The given identifier is `null`.
      See Also:
        `ContainerConstant`, `ContainerDefinition`, `DefinitionObject.getAUID()`

    - #### addEssenceContainer

          void addEssenceContainer(AUID essenceContainerID)
                            throws NullPointerException

      Adds an essence container to the set of essence containers identifiers of this preface, which identify the internal essence containers used in the file. The essence container property is optional. Adding an optional identifier causes the essence containers property to become present.

      Parameters:
        `essenceContainerID` - Essence container identifier to add to the set of essence containers of this prefance.
      Throws:
        `NullPointerException` - Cannot add a null identifier to the set of essence containers.
      See Also:
        `DefinitionObject.getAUID()`, `getEssenceContainers()`, `isEssenceContainerPresent(AUID)`

    - #### countDescriptiveSchemes

          @UInt32
          int countDescriptiveSchemes()

      Returns the total number of descriptive metadata schemes present for this preface, which identify the descriptive metadata schemes used in the file.

      Returns:
        Total number of descriptive schemes present in the file of this preface.

    - #### clearDescriptiveSchemes

          void clearDescriptiveSchemes()

      Remove all descriptive schemes from this preface, omitting this optional property.

      See Also:
        `getDescriptiveSchemes()`, `countDescriptiveSchemes()`

    - #### getDescriptiveSchemes

          Set<AUID> getDescriptiveSchemes()
                                   throws PropertyNotPresentException

      Returns the set of descriptive schemes of this preface, which identify the descriptive metadata schemes used in the file.

      Returns:
        Copy of the identifiers of the descriptive schemes of this preface.
      Throws:
        `PropertyNotPresentException` - The optional set of descriptive metadata schemes is not present in this preface.
      See Also:
        `DescriptiveFramework`, `DescriptiveClip`, `Root.getRootExtensions()`, `DescriptiveMarker.getDescriptiveMetadataScheme()`, `ExtensionScheme`

    - #### isDescriptiveSchemePresent

          @Bool
          boolean isDescriptiveSchemePresent(AUID descriptiveSchemeId)
                                            throws NullPointerException

      Returns `true` if the descriptive metadata scheme with the given identifier is in set of schemes of this preface; otherwise `false`.

      Parameters:
        `descriptiveSchemeId` - Identifier of the descriptive metadata scheme to check for.
      Returns:
        Does the given identifier match that of a descriptive metadata scheme in this preface?
      Throws:
        `NullPointerException` - The given identifier is `null`.
      See Also:
        `DescriptiveFramework`, `DescriptiveClip`

    - #### addDescriptiveScheme

          void addDescriptiveScheme(AUID descriptiveSchemeID)
                             throws NullPointerException

      Adds the given descriptive metadata scheme identifier to the set of schemes of this preface, which identify the descriptive metadata schemes used in the file. If the optional set of descriptive metadata schemes property is omitted, it will become present after successful completion of this method.

      Parameters:
        `descriptiveSchemeID` - Descriptive metadata scheme identifier to add to the set of this preface.
      Throws:
        `NullPointerException` - The given descriptive metadata scheme identifier is `null`.
      See Also:
        `DescriptiveFramework`, `DescriptiveClip`

    - #### removeDescriptiveScheme

          void removeDescriptiveScheme(AUID descriptiveSchemeID)
                                throws NullPointerException,
                                       InvalidParameterException,
                                       PropertyNotPresentException

      Removes the given descriptive metadata scheme identifier from the set of schemes of this preface, which identify the descriptive metadata schemes used in the file. If the

      Parameters:
        `descriptiveSchemeID` - Descriptive metadata scheme identifier to remove from the set of schemes of this preface.
      Throws:
        `NullPointerException` - The given scheme identifier is `null`.
        `InvalidParameterException` - The given descriptive scheme identifier is not present in the list of schemes of this preface.
        `PropertyNotPresentException` - The optional set of descriptive metadata schemes property is not present in this preface.
      See Also:
        `DescriptiveFramework`, `DescriptiveClip`

    - #### getByteOrder

          ByteOrder getByteOrder()

      Returns the byte order of the file this preface was read from.

      Returns:
        Byte order of the file this preface was read from.
      See Also:
        `ByteOrder.getAAFByteOrderCode()`

    - #### getObjectModelVersion

          @UInt32
          int getObjectModelVersion()

      Returns the version of the persistent storage format for objects of this preface.

      Returns:
        Version of the persistent storage format for objects.

    - #### getApplicationSchemes

          Set<AUID> getApplicationSchemes()
                                   throws PropertyNotPresentException

      Returns the set of identifiers for application metadata schemes used in the file. This is an optional property.

      Returns:
        Set of identifiers for application metadata schemes used in the file.
      Throws:
        `PropertyNotPresentException` - The optional application schemes property is not present in this preface.
      See Also:
        `isApplicationSchemePresent(AUID)`, `addApplicationScheme(AUID)`, `ExtensionScheme`

    - #### addApplicationScheme

          void addApplicationScheme(AUID applicationSchemeID)
                             throws NullPointerException

      Adds the identifier of an application metadata scheme to the set of schemes used in this file. If this optional property is omitted, successful completion of this property will make the property present.

      Parameters:
        `applicationSchemeID` - Application metadata scheme identifier to add.
      Throws:
        `NullPointerException` - Cannot add a `null` identifier to the set of application schemes.
      See Also:
        `getApplicationSchemes()`, `isApplicationSchemePresent(AUID)`

    - #### isApplicationSchemePresent

          boolean isApplicationSchemePresent(AUID applicationSchemeID)
                                      throws PropertyNotPresentException,
                                             NullPointerException

      Returns `true` if the given identifier matches one of the application metadata scheme stated to be in the file.

      Parameters:
        `applicationSchemeID` - Application scheme identifier for check for.
      Returns:
        Does the given identifier match that of an application metadata scheme in this preface?
      Throws:
        `PropertyNotPresentException` - The optional application schemes property is not present in this preface.
        `NullPointerException` - Cannot test for an application scheme using a `null` pointer.
      See Also:
        `getApplicationSchemes()`

    - #### countApplicationSchemes

          int countApplicationSchemes()

      Returns the number of application metadata schemes recorded in the preface for this file.

      Returns:
        Number of application metadata schemes of this preface.
      See Also:
        `getApplicationSchemes()`

    - #### clearApplicationSchemes

          void clearApplicationSchemes()

      Remove all application schemes from this preface, omitting this optional property.

      See Also:
        `getApplicationSchemes()`, `countApplicationSchemes()`

    - #### removeApplicationScheme

          void removeApplicationScheme(AUID applicationSchemeID)
                                throws NullPointerException,
                                       InvalidParameterException,
                                       PropertyNotPresentException

      Remove an application metadata scheme from the set of application schemes of this file.

      Parameters:
        `applicationSchemeID` - Identifier of the application metadata scheme to remove.
      Throws:
        `NullPointerException` - Cannot remove an application metadata schemes using a `null` identifier.
        `InvalidParameterException` - The given application metadata scheme identifier is not present in the set of application schemes of this preface.
        `PropertyNotPresentException` - The optional application schemes property is not present for this preface.
      See Also:
        `getApplicationSchemes()`, `isApplicationSchemePresent(AUID)`

    - #### updateDictionaries

          boolean updateDictionaries()

      Iterate through the content storage packages and make sure the dictionary contains all the referenced definitions, adding any missing definitions.

      Returns:
        Does the dictionary now contain all of the required definitions?
      See Also:
        `getDictionaries()`

    - #### clone

          Preface clone()

      Create a cloned copy of this preface.

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

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