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

tv.amwa.maj.model

## Interface ContentStorage

- All Superinterfaces:
    InterchangeObject, MediaEntity, MetadataObject
  All Known Implementing Classes:
    ContentStorageImpl

      public interface ContentStorage
      extends InterchangeObject

  Specifies storage for content that has package and essence data within it. An AAF file shall have exactly one content storage.

  Note that there is no requirement for every package stored in a content storage to have its essence data stored within the same content storage. However, it is likely that if some essence data is stored in this content storage, its associated metadata file source package is also stored.

  See Also:
    `Preface.getContentStorageObject()`, `TypeDefinitions.ContentStorageStrongReference`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addEssenceDataObject(EssenceData essenceData)` Adds the given essence data item to the set of those stored in this content storage..
    `void` | `addPackage(Package packageToAdd)` Adds the given package to the set of packages in this content storage.
    `ContentStorage` | `clone()` Create a cloned copy of this content storage.
    `int` | `countEssenceDataObjects()` Returns the total number of essence data items in this content storage.
    `int` | `countPackages()` Returns the total number of packages in this content storage.
    `int` | `countPackages(PackageKind packageKind)` Find the number of matches for the given package kind stored in this content storage.
    `Set<? extends EssenceData>` | `enumEssenceDataObjects()` Returns the complete set of essence data contained within this content storage object.
    `Set<? extends EssenceData>` | `getEssenceDataObjects()` Returns the complete set of essence data contained within this content storage object.
    `Set<? extends EssenceData>` | `getEssenceDataObjects(CriteriaType mediaCriteria)` Returns the set of essence data contained within this content storage object, filtered according to the media criteria provided.
    `Set<? extends Package>` | `getPackages()` Returns a set of all packages stored in this content storage.
    `Set<? extends Package>` | `getPackages(SearchCriteria searchCriteria)` Returns a set of packages from this content storage according to a given search criteria.
    `boolean` | `isEssenceDataPresent(PackageID filePackageID)` Returns `true` if essence data identified by the given package id is contained in this content storage.
    `EssenceData` | `lookupEssenceDataObject(PackageID packageId)` Looks up and returns an essence data item stored in this content storage that matches the given package id.
    `Package` | `lookupPackage(PackageID packageID)` Returns the package that matches the given package id from the set of packages in this content storage.
    `void` | `removeEssenceDataObject(EssenceData essenceData)` Removes the given essence data item from the set stored in this content storage.
    `void` | `removePackage(Package packageToRemove)` Removes the given package from the set stored in this content storage.

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

    - #### lookupPackage

          Package lookupPackage(PackageID packageID)
                         throws NullPointerException,
                                PackageNotFoundException

      Returns the package that matches the given package id from the set of packages in this content storage.

      Parameters:
        `packageID` - The identifier of the package to find in this content storage.
      Returns:
        Package with the given identifier from this content storage.
      Throws:
        `NullPointerException` - The given package identifier is `null`.
        `PackageNotFoundException` - The requested package is not stored in this content storage.

    - #### countPackages

          @NumTracks
          int countPackages(PackageKind packageKind)
                                throws NullPointerException

      Find the number of matches for the given package kind stored in this content storage.

      Parameters:
        `packageKind` - The kind of package to count.
      Returns:
        Total number of packages of the given package kind stored in this content storage.
      Throws:
        `NullPointerException` - The given package kind is `null`.
      See Also:
        `countPackages()`

    - #### countPackages

          int countPackages()

      Returns the total number of packages in this content storage.

      Returns:
        Total number of packages in this content storage.
      See Also:
        `countPackages(PackageKind)`

    - #### getPackages

          Set<? extends Package> getPackages(SearchCriteria searchCriteria)

      Returns a set of packages from this content storage according to a given search criteria. If the search criteria is `null` then all of the packages in storage are returned.

      Parameters:
        `searchCriteria` - Search criteria to filter the set of stored packages of this content storage with.
      Returns:
        Shallow copy of the set of all the packages matching the given search criteria.
      See Also:
        `SearchCriteria`, `Preface.getPackages(SearchCriteria)`, `TypeDefinitions.PackageStrongReferenceSet`

    - #### getPackages

          Set<? extends Package> getPackages()

      Returns a set of all packages stored in this content storage.

      Returns:
        Shallow copy of the set of all the packages in this content storage.
      See Also:
        `getPackages(SearchCriteria)`, `Preface.getPackages(SearchCriteria)`

    - #### addPackage

          void addPackage(Package packageToAdd)
                   throws NullPointerException,
                          DuplicatePackageIDException

      Adds the given package to the set of packages in this content storage.

      Parameters:
        `packageToAdd` - Package to add to this content storage.
      Throws:
        `NullPointerException` - The given package is `null`.
        `DuplicatePackageIDException` - The given package is already contained in this content storage.

    - #### removePackage

          void removePackage(Package packageToRemove)
                      throws NullPointerException,
                             PackageNotFoundException

      Removes the given package from the set stored in this content storage.

      Parameters:
        `packageToRemove` - Package to remove from this content storage.
      Throws:
        `NullPointerException` - The given package to remove is `null`.
        `PackageNotFoundException` - The given package is not current contained in this content storage.

    - #### countEssenceDataObjects

          @UInt32
          int countEssenceDataObjects()

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

      Returns:
        Total number of essence data items.

    - #### isEssenceDataPresent

          @Bool
          boolean isEssenceDataPresent(PackageID filePackageID)
                                      throws NullPointerException

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

      Parameters:
        `filePackageID` - Identifier of the essence data to check for within this content storage.
      Returns:
        True if the essence data is found in this content storage.
      Throws:
        `NullPointerException` - One or more of the arguments in `null`.

    - #### enumEssenceDataObjects

          Set<? extends EssenceData> enumEssenceDataObjects()
                                                     throws PropertyNotPresentException

      Returns the complete set of essence data contained within this content storage object. Essence data does not have to be carried in the same container as the metadata, so this is an optional property.

      Calling this method produces the same result as calling `getEssenceData(CriteriaType.AnyRepresentation)`.

      Returns:
        Shallow copy of the set of essence data stored in this content storage.
      Throws:
        `PropertyNotPresentException` - No essence data objects are present in this content storage.
      See Also:
        `getEssenceDataObjects()`, `Preface.enumEssenceData()`, `TypeDefinitions.EssenceDataStrongReferenceSet`

    - #### getEssenceDataObjects

          Set<? extends EssenceData> getEssenceDataObjects()
                                                    throws PropertyNotPresentException

      Returns the complete set of essence data contained within this content storage object. Essence data does not have to be carried in the same container as the metadata, so this is an optional property.

      Calling this method produces the same result as calling `getEssenceData(CriteriaType.AnyRepresentation)`.

      Returns:
        Shallow copy of the set of essence data stored in this content storage.
      Throws:
        `PropertyNotPresentException` - No essence data objects are present in this content storage.
      See Also:
        `getEssenceDataObjects(CriteriaType)`, `enumEssenceDataObjects()`, `Preface.enumEssenceData()`, `TypeDefinitions.EssenceDataStrongReferenceSet`

    - #### getEssenceDataObjects

          Set<? extends EssenceData> getEssenceDataObjects(CriteriaType mediaCriteria)

      Returns the set of essence data contained within this content storage object, filtered according to the media criteria provided.

      If the mediaCriteria is set to `CriteriaType.AnyRepresentation`, all essence data is returned.

      Parameters:
        `mediaCriteria` - Criteria to use to select the required essence data.
      Returns:
        Shallow copy of the set of essence stored in the content storage object.
      See Also:
        `enumEssenceDataObjects()`, `Preface.getEssenceData(CriteriaType)`, `TypeDefinitions.EssenceDataStrongReferenceSet`

    - #### addEssenceDataObject

          void addEssenceDataObject(EssenceData essenceData)
                             throws DuplicatePackageIDException,
                                    NullPointerException

      Adds the given essence data item to the set of those stored in this content storage..

      Parameters:
        `essenceData` - Essence data object to add to those stored in this content storage.
      Throws:
        `DuplicatePackageIDException` - The given package has already been added. The validation is done by comparing package ids, which should be unique amongst all essence data in a content storage unit.
        `NullPointerException` - The given essence data item is `null`.
      See Also:
        `EssenceData.getLinkedPackageID()`

    - #### removeEssenceDataObject

          void removeEssenceDataObject(EssenceData essenceData)
                                throws NullPointerException,
                                       EssenceNotFoundException

      Removes the given essence data item from the set stored in this content storage.

      Parameters:
        `essenceData` - Essence data to remove from this content storage.
      Throws:
        `NullPointerException` - The given essence data item is `null`.
        `EssenceNotFoundException` - The given essence data item is not currently contained in this content storage.

    - #### lookupEssenceDataObject

          EssenceData lookupEssenceDataObject(PackageID packageId)
                                       throws NullPointerException,
                                              PackageNotFoundException

      Looks up and returns an essence data item stored in this content storage that matches the given package id.

      Parameters:
        `packageId` - The package id identifying the essence data stored in this content storage.
      Returns:
        Essence data stored in this content storage with the given package id.
      Throws:
        `NullPointerException` - The given essece data package id is `null`.
        `PackageNotFoundException` - The requested essence data was not found stored in this content storage.

    - #### clone

          ContentStorage clone()

      Create a cloned copy of this content storage.

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

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