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.
| 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.
|
| 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.
|
addApplicationPlugin, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getGeneration, getLinkedGenerationID, getObjectClass, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setObjectClass, toStringgetPersistentID, setPersistentIndexstatic 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.
Package lookupPackage(PackageID packageID) throws NullPointerException, PackageNotFoundException
Returns the package that matches the given package id stored in the content storage of this preface.
packageID - The identifier of the package to look up in the content storage of this preface.NullPointerException - The given package identifier is null.PackageNotFoundException - A package with the given identifier was not found in the content storage of
this preface.getContentStorageObject(),
ContentStorage.lookupPackage(PackageID)@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.
packageKind - The kind of packages to count.getContentStorageObject(),
ContentStorage.countPackages(PackageKind)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.
searchCriteria - Search criteria to use to filter the set of packages
returned.null. The
set does not clone packages it contains.getContentStorageObject(),
getPackages(),
ContentStorage.getPackages(SearchCriteria),
ContentStorage.getPackages()Set<? extends Package> getPackages()
Returns all the packages stored in the content storage of this preface.
getContentStorageObject(),
getPackages(SearchCriteria),
ContentStorage.getPackages()void addPackage(Package packageToAdd) throws NullPointerException, DuplicatePackageIDException
Adds a package to the content storage of this preface.
packageToAdd - Package to add to the content storage of this preface.NullPointerException - The given package is null.DuplicatePackageIDException - A package with the same package id is already
contained in the content storage of this preface.getContentStorageObject(),
ContentStorage.addPackage(Package)void removePackage(Package packageToRemove) throws NullPointerException, PackageNotFoundException
Removes the given package from the content storage of this preface.
packageToRemove - Package to remove from the preface.NullPointerException - The given package to remove is null.PackageNotFoundException - The given package is not contained
in the content storage of this preface.getContentStorageObject(),
ContentStorage.removePackage(Package)@UInt32 int countEssenceData()
Returns the total number of essence data items stored in the content storage of this preface.
getContentStorageObject(),
ContentStorage.countEssenceDataObjects()@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.
filePackageID - Identifier of a file package that may be present in the content storage of this preface.NullPointerException - The given package id is null.InvalidParameterException - The given file package id does not identify a file source package.getContentStorageObject(),
ContentStorage.isEssenceDataPresent(PackageID)Set<? extends EssenceData> enumEssenceData()
Returns a set of all essence data stored in the content storage of this preface.
getEssenceData(CriteriaType),
getContentStorageObject(),
ContentStorage.enumEssenceDataObjects()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().
mediaCriteria - Criteria for selecting essence data from storage.NullPointerExceptiongetEssenceData(),
enumEssenceData(),
getContentStorageObject(),
ContentStorage.getEssenceDataObjects(CriteriaType)Set<? extends EssenceData> getEssenceData()
Returns all the essence data objects from the content storage of this preface.
enumEssenceData(),
getEssenceData(CriteriaType),
ContentStorage.getEssenceDataObjects()void addEssenceData(EssenceData essenceData) throws DuplicatePackageIDException, NullPointerException
Adds an essence data item to the content storage of this preface.
essenceData - Essence data to add to the content storage of this preface.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.getContentStorageObject(),
ContentStorage.addEssenceDataObject(EssenceData)void removeEssenceData(EssenceData essenceData) throws NullPointerException, EssenceNotFoundException
Removes the given essence data item from the content storage of this preface.
essenceData - Essence data to remove from the content storage of this preface.NullPointerException - The given essence data item is null.EssenceNotFoundException - The given essence data item is not contained in the
content storage of this preface.getContentStorageObject(),
ContentStorage.removeEssenceDataObject(EssenceData)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.
packageID - Identifier for essence data stored in the content storage of this preface.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.getContentStorageObject(),
ContentStorage.lookupEssenceDataObject(PackageID)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.
TypeDefinitions.DictionaryStrongReferenceIdentification getLastIdentification()
Returns the identification of the last application that modified the file.
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.
generation - Unique generation identifier to retrieve from the list of identifications
of this preface.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.@UInt32 int countIdentifications()
Returns the number of identifications in the 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.
TypeDefinitions.IdentificationStrongReferenceVectorvoid 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.
identification - Identification to append to the list of identifications of this preface.NullPointerException - The given identification is null.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.
index - 0-based index of the identification to retrieve from the list of identifications
of this preface.IndexOutOfBoundsException - The given index is outside the acceptable range for the
current list of identifications of this preface.ProductVersion getMajApiVersion()
Return the version of the MAJ API currently running on this machine, which implements these interfaces.
getLastIdentification(),
Identification.getRefImplVersion()VersionType getFormatVersion()
Return the file version property of the preface.
TimeStamp getFileLastModified()
Return the last modified time stamp of this preface, which specifies the time and date that this file was last modified.
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.
fileLastModified - Time stamp for the most recent modification of the file.NullPointerException - Cannot set the timestamp using a null value.getLastIdentification()ContentStorage getContentStorageObject()
Returns the content storage of this preface. This is the Content property of a preface.
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.
PropertyNotPresentException - The optional primary package identifier is not present
in the preface.PackageID.getMaterial()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.
primaryPackageID - Primary package identifier for the file of this preface.PackageID.getMaterial()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.
PropertyNotPresentException - Property is not present in the preface.OperationalPatternConstantvoid 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.
operationalPatternId - Operational pattern identifier for the preface.NullPointerException - The given operational pattern identifier is null.OperationalPatternConstantvoid 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.
ContainerDefinition@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.
PropertyNotPresentException - Essence containers are not present
in the file of the preface.void clearEssenceContainers()
Remove all essence containers from this preface, omitting this optional property.
getEssenceContainers(),
countEssenceContainers()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.
PropertyNotPresentException - The optional set of essence containers is not present
for this preface.ContainerConstant,
ContainerDefinition@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.
essenceContainerId - Identifier of the type of essence container to check for.NullPointerException - The given identifier is null.ContainerConstant,
ContainerDefinition,
DefinitionObject.getAUID()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.
essenceContainerID - Essence container identifier to add to the set of essence
containers of this prefance.NullPointerException - Cannot add a null identifier to the set of essence
containers.DefinitionObject.getAUID(),
getEssenceContainers(),
isEssenceContainerPresent(AUID)@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.
void clearDescriptiveSchemes()
Remove all descriptive schemes from this preface, omitting this optional property.
getDescriptiveSchemes(),
countDescriptiveSchemes()Set<AUID> getDescriptiveSchemes() throws PropertyNotPresentException
Returns the set of descriptive schemes of this preface, which identify the descriptive metadata schemes used in the file.
PropertyNotPresentException - The optional set of descriptive metadata schemes is
not present in this preface.DescriptiveFramework,
DescriptiveClip,
Root.getRootExtensions(),
DescriptiveMarker.getDescriptiveMetadataScheme(),
ExtensionScheme@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.
descriptiveSchemeId - Identifier of the descriptive metadata scheme to check for.NullPointerException - The given identifier is null.DescriptiveFramework,
DescriptiveClipvoid 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.
descriptiveSchemeID - Descriptive metadata scheme identifier to add to the set of
this preface.NullPointerException - The given descriptive metadata scheme identifier is null.DescriptiveFramework,
DescriptiveClipvoid 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
descriptiveSchemeID - Descriptive metadata scheme identifier to remove from the
set of schemes of this preface.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.DescriptiveFramework,
DescriptiveClipByteOrder getByteOrder()
Returns the byte order of the file this preface was read from.
ByteOrder.getAAFByteOrderCode()@UInt32 int getObjectModelVersion()
Returns the version of the persistent storage format for objects of this preface.
Set<AUID> getApplicationSchemes() throws PropertyNotPresentException
Returns the set of identifiers for application metadata schemes used in the file. This is an optional property.
PropertyNotPresentException - The optional application schemes property is not
present in this preface.isApplicationSchemePresent(AUID),
addApplicationScheme(AUID),
ExtensionSchemevoid 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.
applicationSchemeID - Application metadata scheme identifier to add.NullPointerException - Cannot add a null identifier to the set of application schemes.getApplicationSchemes(),
isApplicationSchemePresent(AUID)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.
applicationSchemeID - Application scheme identifier for check for.PropertyNotPresentException - The optional application schemes property is not present in this
preface.NullPointerException - Cannot test for an application scheme using a null pointer.getApplicationSchemes()int countApplicationSchemes()
Returns the number of application metadata schemes recorded in the preface for this file.
getApplicationSchemes()void clearApplicationSchemes()
Remove all application schemes from this preface, omitting this optional property.
getApplicationSchemes(),
countApplicationSchemes()void removeApplicationScheme(AUID applicationSchemeID) throws NullPointerException, InvalidParameterException, PropertyNotPresentException
Remove an application metadata scheme from the set of application schemes of this file.
applicationSchemeID - Identifier of the application metadata scheme to remove.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.getApplicationSchemes(),
isApplicationSchemePresent(AUID)boolean updateDictionaries()
Iterate through the content storage packages and make sure the dictionary contains all the referenced definitions, adding any missing definitions.
getDictionaries()Preface clone()
Create a cloned copy of this preface.
clone in interface InterchangeObjectclone in interface MediaEntity(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.