tv.amwa.maj.iface
Interface Header

All Superinterfaces:

InterchangeObject

All Known Implementing Classes:

Header

public interface Header
extends InterchangeObject

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

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

Author:

Richard Cartwright

See Also:

makeHeader()

Field Summary

static int

OBJECTMODELVERSION_DEFAULT Default value for the object model version property of a header object which is 1.

Method Summary

void	addDescriptiveScheme(AUID descriptiveSchemeId) Adds the given descriptive metadata scheme identifier to the set of schemes of this header, which identify the descriptive metadata schemes used in the file.
void	addEssenceData(EssenceData essenceData) Adds an essence data item to the content storage of this header.
void	addMob(Mob mob) Adds a mob to the content storage of this header.
void	appendIdentification(Identification identification) Appends the given identification to the list of identifications of this header, which each identify an application that created or modified the file.
int	countDescriptiveSchemes() Returns the total number of descriptive metadata schemes present for this header, which identify the descriptive metadata schemes used in the file.
int	countEssenceContainers() Returns the total number of essence containers of this header, 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 header.
int	countIdentifications() Returns the number of identifications in the header, which each identify an application that created or modified the file.
int	countMobs(MobKind mobKind) Returns the number of matches for the given mob kind within the content storage of this header.
Set<? extends EssenceData>	enumEssenceData() Returns a set of all essence data stored in the content storage of this header.
ContentStorage	getContentStorage() Returns the content storage of this header.
Set<AUID>	getDescriptiveSchemes() Returns the set of descriptive schemes of this header, which identify the descriptive metadata schemes used in the file.
Dictionary	getDictionary() Returns the dictionary of this header, which contains all the definitions of the file.
Set<AUID>	getEssenceContainers() Returns the set of essence containers of this header, which identify the internal essence containers used in the file.
Set<? extends EssenceData>	getEssenceData(CriteriaType mediaCriteria) Returns a set of essence data from the content storage of this header that matches the given media criteria.
VersionType	getFileRevision() Return the file version property of the header.
Identification	getIdentificationAt(int index) Retrieves the identification at the given index through the list of identifications of this header, which each identify an application that created or modified the file.
List<? extends Identification>	getIdentifications() Returns the list of identifications contained within this header, which each identify an application that created or modified the file.
Identification	getLastIdentification() Returns the identification of the last application that modified the file.
TimeStamp	getLastModified() Return the last modified time stamp of this header, which specifies the time and date that this file was last modified.
ProductVersion	getMajApiVersion() Return the version of the MAJ API currently running on this machine, which implements these interfaces.
Set<? extends Mob>	getMobs(SearchCriteria searchCriteria) Returns a set of mobs stored in the content storage of this header that match the given search criteria.
AUID	getOperationalPattern() Returns the identifier of the MXF operational pattern or AAF protocol that the file of this header complies with.
Mob	getPrimaryMob() Returns the primary mob for the file of this header, which specifies the mob that the application treats as the default.
boolean	isDescriptiveSchemePresent(AUID descriptiveSchemeId) Returns true if the descriptive metadata scheme with the given identifier is in set of schemes of this header; otherwise false.
boolean	isEssenceContainerPresent(AUID essenceContainerId) Returns true if the essence containers with the given identifier is present for this header; otherwise false.
boolean	isEssenceDataPresent(MobID fileMobId) Returns true if essence data identified by the given mob id is present in the content storage of this header.
EssenceData	lookupEssenceData(MobID mobId) Looks up and returns the essence data that matches the given mob id from the content storage of this header.
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 header.
Mob	lookupMob(MobID mobId) Returns the mob that matches the given mob id stored in the content storage of this header.
void	removeDescriptiveScheme(AUID descriptiveSchemeId) Removes the given descriptive metadata scheme identifier from the set of schemes of this header, 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 header.
void	removeMob(Mob mob) Removes the given mob from the content storage of this header.
void	setOperationalPattern(AUID operationalPatternId) Sets the MXF operational pattern or AAF protocol that the file of this header complies with.
void	setPrimaryMob(Mob primaryMob) Sets the primary mob for the file of the header, which specifies the mob that the application treats as the default.
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.iface.InterchangeObject

countProperties, createOptionalPropertyValue, disableGenerationTracking, enableGenerationTracking, getDefinition, getGeneration, getGenerationAUID, getProperties, getPropertyValue, isGenerationTracked, isPropertyPresent, omitOpionalProperty, setPropertyValue

Field Detail

OBJECTMODELVERSION_DEFAULT

static final int OBJECTMODELVERSION_DEFAULT

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

See Also:

Constant Field Values

Method Detail

lookupMob

Mob lookupMob(MobID mobId)
              throws NullPointerException,
                     MobNotFoundException

Returns the mob that matches the given mob id stored in the content storage of this header.

Parameters:

mobId - The identifier of the mob to look up in the content storage of this header.

Returns:

The mob from the storage with the matching identifier.

Throws:

NullPointerException - The given mob identifier is null.

MobNotFoundException - A mob with the given identifier was not found in the content storage of this header.

See Also:

getContentStorage(), ContentStorage.lookupMob(MobID)

countMobs

@UInt32
int countMobs(MobKind mobKind)

Returns the number of matches for the given mob kind within the content storage of this header. Use MobKind.AllMob to count the total number of mobs.

Parameters:

mobKind - The kind of mobs to count.

Returns:

Total number of mobs matching the given mob kind in the content storage of this header.

See Also:

getContentStorage(), ContentStorage.countMobs(MobKind)

getMobs

Set<? extends Mob> getMobs(SearchCriteria searchCriteria)

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

Parameters:

searchCriteria - Search criteria to use to filter the set of mobs returned.

Returns:

Set of mobs matching the search criteria, or the set of all mobs if the search criteria was null. The set does not clone mobs it contains.

See Also:

getContentStorage(), ContentStorage.getMobs(SearchCriteria)

addMob

void addMob(Mob mob)
            throws NullPointerException,
                   DuplicateMobIDException

Adds a mob to the content storage of this header.

Parameters:

mob - Mob to add to the content storage of this header.

Throws:

NullPointerException - The given mob is null.

DuplicateMobIDException - A mob with the same mob id is already contained in the content storage of this header.

See Also:

getContentStorage(), ContentStorage.addMob(Mob)

removeMob

void removeMob(Mob mob)
               throws NullPointerException,
                      MobNotFoundException

Removes the given mob from the content storage of this header.

Parameters:

mob - Mob to remove from the header.

Throws:

NullPointerException - The given mob to remove is null.

MobNotFoundException - The given mob is not contained in the content storage of this header.

See Also:

getContentStorage(), ContentStorage.removeMob(Mob)

countEssenceData

@UInt32
int countEssenceData()

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

Returns:

Total number of essence data items stored in the content storage of this header.

See Also:

getContentStorage(), ContentStorage.countEssenceData()

isEssenceDataPresent

@Bool
boolean isEssenceDataPresent(MobID fileMobId)
                             throws NullPointerException,
                                    InvalidParameterException

Returns true if essence data identified by the given mob id is present in the content storage of this header.

Parameters:

fileMobId - Identifier of a file mob that may be present in the content storage of this header.

Returns:

Does the given mob id match that of an essence data item stored in thie content storage of this header?

Throws:

NullPointerException - The given mob id is null.

InvalidParameterException - The given file mob id does not identify a file source mob.

See Also:

getContentStorage(), ContentStorage.isEssenceDataPresent(MobID)

enumEssenceData

Set<? extends EssenceData> enumEssenceData()

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

Returns:

Shallow copy of the set of all essence data stored in the content storage of this header.

See Also:

getEssenceData(CriteriaType), getContentStorage(), ContentStorage.enumEssenceData()

getEssenceData

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

Returns a set of essence data from the content storage of this header 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 header 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 header. Note that the essence data items are not cloned.

Throws:

NullPointerException

See Also:

enumEssenceData(), getContentStorage(), ContentStorage.getEssenceData(CriteriaType)

addEssenceData

void addEssenceData(EssenceData essenceData)
                    throws DuplicateMobIDException,
                           NullPointerException

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

Parameters:

essenceData - Essence data to add to the content storage of this header.

Throws:

DuplicateMobIDException - Essence data with the same mob id is already contained in the content storage of this header.

NullPointerException - The given essence data item is null.

See Also:

getContentStorage(), ContentStorage.addEssenceData(EssenceData)

removeEssenceData

void removeEssenceData(EssenceData essenceData)
                       throws NullPointerException,
                              EssenceNotFoundException

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

Parameters:

essenceData - Essence data to remove from the content storage of this header.

Throws:

NullPointerException - The given essence data item is null.

EssenceNotFoundException - The given essence data item is not contained in the content storage of this header.

See Also:

getContentStorage(), ContentStorage.removeEssenceData(EssenceData)

lookupEssenceData

EssenceData lookupEssenceData(MobID mobId)
                              throws NullPointerException,
                                     MobNotFoundException

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

Parameters:

mobId - Identifier for essence data stored in the content storage of this header.

Returns:

Essence data stored in the content storage of this header with the given mob id.

Throws:

NullPointerException - The given mob id is null.

MobNotFoundException - Essence data identified with the given mob id is not stored in the content storage of the header.

See Also:

getContentStorage(), ContentStorage.lookupEssenceData(MobID)

getDictionary

Dictionary getDictionary()

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

Returns:

AAF dictionary of the header.

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 header.

Parameters:

generation - Unique generation identifier to retrieve from the list of identifications of this header.

Returns:

Identification with the given identifier from the list of identifications of this header.

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 header.

countIdentifications

@UInt32
int countIdentifications()

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

Returns:

Number of identifications in the list of identifications of this header.

getIdentifications

List<? extends Identification> getIdentifications()

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

Returns:

Shallow copy of the list of identifications in this header.

appendIdentification

void appendIdentification(Identification identification)
                          throws NullPointerException

Appends the given identification to the list of identifications of this header, 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 header.

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 header, 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 header.

Returns:

Identification at the given index.

Throws:

IndexOutOfBoundsException - The given index is outside the acceptable range for the current list of identifications of this header.

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()

getFileRevision

VersionType getFileRevision()

Return the file version property of the header.

Returns:

File version.

getLastModified

TimeStamp getLastModified()

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

Returns:

Last modification time stamp.

getContentStorage

ContentStorage getContentStorage()

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

Returns:

Content storage of this object.

getPrimaryMob

Mob getPrimaryMob()
                  throws PropertyNotPresentException

Returns the primary mob for the file of this header, which specifies the mob that the application treats as the default. This is an optional property.

Returns:

Primary mob for this header.

Throws:

PropertyNotPresentException - Property is not present in the header.

setPrimaryMob

void setPrimaryMob(Mob primaryMob)

Sets the primary mob for the file of the header, which specifies the mob that the application treats as the default. Set this optional property to null to omit it.

Parameters:

primaryMob - Primary mob for the file of the header.

getOperationalPattern

AUID getOperationalPattern()
                           throws PropertyNotPresentException

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

Returns:

Operational pattern that the file of this header complies with.

Throws:

PropertyNotPresentException - Property is not present in the header.

See Also:

OperationalPatternConstant

setOperationalPattern

void setOperationalPattern(AUID operationalPatternId)
                           throws NullPointerException

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

Parameters:

operationalPatternId - Operational pattern identifier for the header.

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 mobs in the file of the header.

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 header, which identify the internal essence containers used in the file.

Returns:

Total number of essence containers present in the file of the header.

Throws:

PropertyNotPresentException - Essence containers are not present in the file of the header.

getEssenceContainers

Set<AUID> getEssenceContainers()
                               throws PropertyNotPresentException

Returns the set of essence containers of this header, 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 header. The identifiers are cloned.

Throws:

PropertyNotPresentException - The optional set of essence containers is not present for this header.

See Also:

ContainerConstant, ContainerDefinition, ContainerDefinition.forIdentification(AUID)

isEssenceContainerPresent

@Bool
boolean isEssenceContainerPresent(AUID essenceContainerId)
                                  throws NullPointerException,
                                         PropertyNotPresentException

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

Parameters:

essenceContainerId - Identifier of the type of essence container to check for.

Returns:

Is the given essence container identifier in this header?

Throws:

NullPointerException

PropertyNotPresentException - Essence containers are not present in the property.

See Also:

ContainerConstant, ContainerDefinition, DefinitionObject.getAUID()

countDescriptiveSchemes

@UInt32
int countDescriptiveSchemes()

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

Returns:

Total number of descriptive schemes present in the file of this header.

getDescriptiveSchemes

Set<AUID> getDescriptiveSchemes()
                                throws PropertyNotPresentException

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

Returns:

Copy of the identifiers of the descriptive schemes of this header.

Throws:

PropertyNotPresentException - The optional set of descriptive metadata schemes is not present in this header.

See Also:

DescriptiveFramework, DescriptiveClip

isDescriptiveSchemePresent

@Bool
boolean isDescriptiveSchemePresent(AUID descriptiveSchemeId)
                                   throws NullPointerException,
                                          PropertyNotPresentException

Returns true if the descriptive metadata scheme with the given identifier is in set of schemes of this header; 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 header?

Throws:

NullPointerException - The given identifier is null.

PropertyNotPresentException - The optional set of descriptive metadata schemes is not present in this header.

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 header, 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 header.

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 header, 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 header.

Throws:

NullPointerException - The given scheme identifier is null.

InvalidParameterException - The given descriptive scheme identifier is not present in the list of schemes of this header.

PropertyNotPresentException - The optional set of descriptive metadata schemes property is not present in this header.

See Also:

DescriptiveFramework, DescriptiveClip