tv.amwa.maj.iface
Interface Mob

All Superinterfaces:

InterchangeObject

All Known Subinterfaces:

CompositionMob, MasterMob, SourceMob

All Known Implementing Classes:

CompositionMob, MasterMob, Mob, SourceMob

public interface Mob
extends InterchangeObject

Specifies a material object (mob), which can describe a composition, essence, or physical media. A mob has a unique identifier and consists of metadata.

Author:

Richard Cartwright

See Also:

ContentStorage.getMobs(tv.amwa.maj.union.SearchCriteria), EssenceData.getFileMob(), MobID

Method Summary

void	appendAttribute(String name, String value) Create and append a new attribute to the collection of attributes contained in this mob, which specify attributes that are under the control of the application (for example filter control).
void	appendAttribute(TaggedValue attribute) Appends an existing attribute to the collection of attributes contained in this mob, which specify attributes that are under the control of the application (for example filter control).
void	appendComment(String category, String comment) Creates a user-defined comment and adds it to the collection of comments of this mob, which specify user comments that are directly classified and set up by the operator (for example Bin columns).
void	appendComment(TaggedValue comment) Append a user comment defined by an existing tagged value to the collection of user comments of this mob, which specify user comments that are directly classified and set up by the operator (for example Bin columns).
void	appendKLVData(KLVData data) Appends an existing user KLV data item to the collection of KLV data items contained in this mob.
EventMobSlot	appendNewEventSlot(Rational editRate, Segment segment, int slotId, String slotName) Creates and returns a new event mob slot with the given edit rate, as well as appending it to the list of slots of this mob.
StaticMobSlot	appendNewStaticSlot(Segment segment, int slotId, String slotName) Creates and returns a new static mob slot with the given property values, as well as appending it to the list of slots of this mob.
TimelineMobSlot	appendNewTimelineSlot(Rational editRate, Segment segment, int slotId, String slotName, long origin) Creates and returns a new timeline mob slot with the given property values, as well as appending it to this mob.
void	appendSlot(MobSlot slot) Appends the given mob slot to the list contained in this mob.
void	changeReference(MobID oldMobId, MobID newMobId) Finds all source clips in this mob that refer to the specified old mob and changes the references to point to the newly specified mob.
Mob	cloneExternal(Depend resolveDependencies, IncludedMedia includedMedia, AAFFile clonedFile) Clones this mob, and optionally all dependent mobs, to a mob that can be used in an external file, keeping the same mob id.
Mob	copy(String destMobName) Creates and returns a new copy of this mob in the same AAF file.
int	countAttributes() Returns the number of attributes in the collection of attributes contained in this mob, which specify attributes that are under the control of the application (for example filter control).
int	countComments() Returns the total number of user comments attached to this mob, which specify user comments that are directly classified and set up by the operator (for example Bin columns).
int	countKLVData() Returns the total number of KLV data items in the collection of KLV data items contained in this mob.
int	countSlots() Returns the number of mob slots contained in this mob.
List<? extends TaggedValue>	getAttributes() Returns the collection of attributes contained in this mob, which specify attributes that are under the control of the application (for example filter control).
List<? extends TaggedValue>	getComments() Returns the collection of all comments attached to this mob, which specify user comments that are directly classified and set up by the operator (for example Bin columns).
TimeStamp	getCreateTime() Returns the creation time of this mob, which is the date and time when this mob was originally created.
List<? extends KLVData>	getKLVData() Returns the collection of KLV data items contained in this mob.
MobID	getMobID() Returns the unique mob identifier (MobID) for this mob.
TimeStamp	getModTime() Returns the modification time for this mob, which is the date and time when this mob was last modified.
String	getName() Returns the name of this mob, as displayed to the end user.
MobSlot	getSlotAt(int index) Returns the mob slot at the given index through the list of mobs contained in this mob.
List<? extends MobSlot>	getSlots() Return the list of mob slots contained in this mob.
AUID	getUsageCode() Returns the usage code for this mob, which specifies how this mob is used.
void	insertSlotAt(int index, MobSlot slot) Inserts the given mob slot into the list of slots contained in this mob at the given index.
MobSlot	lookupSlot(int slotId) Finds and returns the mob slot with the associated slot id from the list of slots for this mob.
TimecodeValue	offsetToMobTimecode(Segment timecodeSegment, long offset) Calculates the timecode at the given offset into the given timecode segment.
void	prependSlot(MobSlot slot) Prepends the given mob slot to the list contained in this mob.
void	removeAttribute(TaggedValue attribute) Removes the given attribute from the collection of attributes contained in this mob, which specify attributes that are under the control of the application (for example filter control).
void	removeComment(TaggedValue comment) Removes the given user comment from the collection of user comments of this mob, which specify user comments that are directly classified and set up by the operator (for example Bin columns).
void	removeKLVData(KLVData data) Removes the given item of KLV data from the collection of KLV data items of this mob.
void	removeSlotAt(int index) Removes the mob slot at the given index from the list of slots contained in this mob.
void	setCreateTime(TimeStamp creationTime) Sets the creation time of this mob, which is the date and time when this mob was originally created.
void	setMobID(MobID mobId) Sets the unique mob identifier (MobID) for this mob.
void	setModTime(TimeStamp lastModified) Sets the modification time for this mob, which is the date and time when this mob was last modified.
void	setName(String name) Sets the name of this mob, as displayed to the end user.
void	setUsageCode(AUID usageCode) Sets this mob's usage code, which specifies how this mob is used.

Methods inherited from interface tv.amwa.maj.iface.InterchangeObject

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

Method Detail

getMobID

@MobIDType
MobID getMobID()

Returns the unique mob identifier (MobID) for this mob.

Returns:

Unique mob id that identifies this mob.

setMobID

void setMobID(@MobIDType
              MobID mobId)
              throws NullPointerException

Sets the unique mob identifier (MobID) for this mob.

Parameters:

mobId - New mob identifier to set for this mob.

Throws:

NullPointerException - The given mob identifier is null.

See Also:

umidFactory()

setName

void setName(@AAFString
             String name)

Sets the name of this mob, as displayed to the end user. Set this optional property to null to omit it.

Parameters:

name - Name of this mob.

getName

@AAFString
String getName()
               throws PropertyNotPresentException

Returns the name of this mob, as displayed to the end user. This is an optional property.

Returns:

Name of this mob.

Throws:

PropertyNotPresentException - The optional name property is not present in this mob.

countSlots

@NumSlots
int countSlots()

Returns the number of mob slots contained in this mob.

Returns:

Number of slots contained by this mob.

appendSlot

void appendSlot(MobSlot slot)
                throws NullPointerException,
                       SlotExistsException

Appends the given mob slot to the list contained in this mob. Note that the index of a mob slot in the list of mob slots is not the same as its slot id.

Parameters:

slot - Mob slot to append to the list of slots contained in this mob.

Throws:

NullPointerException - The given mob slot is null.

SlotExistsException - A mob slot with the same slot id as the given mob slot is already present in this mob.

prependSlot

void prependSlot(MobSlot slot)
                 throws NullPointerException,
                        SlotExistsException

Prepends the given mob slot to the list contained in this mob. Note that the index of a mob slot in the list of mob slots is not the same as its slot id.

Parameters:

slot - Mob slot to prepend to the list of slots contained in this mob.

Throws:

NullPointerException - The given mob slot is null.

SlotExistsException - A mob slot with the same slot id as the given mob slot is already present in this mob.

insertSlotAt

void insertSlotAt(@UInt32
                  int index,
                  MobSlot slot)
                  throws NullPointerException,
                         IndexOutOfBoundsException,
                         SlotExistsException

Inserts the given mob slot into the list of slots contained in this mob at the given index. All existing slots at the given and higher index will be moved up by one index to accommodate the new slot. Note that the index of a mob slot in the list of mob slots is not the same as its slot id.

Parameters:

index - Index where the mob slot is to be inserted.

slot - Mob slot to be inserted into the list contained in this mob.

Throws:

NullPointerException - The given mob slot is null.

IndexOutOfBoundsException - Index is outside the acceptable range for the list of mob slots contained in this mob.

SlotExistsException - A mob slot with the same slot id as the given mob slot is already present in this mob.

removeSlotAt

void removeSlotAt(@UInt32
                  int index)
                  throws IndexOutOfBoundsException

Removes the mob slot at the given index from the list of slots contained in this mob. All existing slots at indices higher than the given index will be moved on one index to accommodate.

Parameters:

index - Index of mob slot to be removed from the list of slots of this mob.

Throws:

IndexOutOfBoundsException - Index is outside the acceptable range for the list of mob slots contained in this mob.

getSlotAt

MobSlot getSlotAt(@UInt32
                  int index)
                  throws IndexOutOfBoundsException

Returns the mob slot at the given index through the list of mobs contained in this mob.

Parameters:

index - Index of mob slot to be returned.

Returns:

Mob slot at the specified index through the list of this mob.

Throws:

IndexOutOfBoundsException - Index is outside the acceptable range for the list of mob slots contained in this mob.

getSlots

List<? extends MobSlot> getSlots()

Return the list of mob slots contained in this mob.

Returns:

Shallow copy of the list of mob slots contained in this mob.

getModTime

TimeStamp getModTime()

Returns the modification time for this mob, which is the date and time when this mob was last modified.

Returns:

Modification time for this mob.

setModTime

void setModTime(TimeStamp lastModified)
                throws NullPointerException

Sets the modification time for this mob, which is the date and time when this mob was last modified. The modification time is initially set to the time that this mob was created.

The MAJ API does not maintain the modification time every time that a mob is updated. Therefore, this method should be called explicitly to change the modification time for this mob.

Parameters:

lastModified - Modification time to set for this mob.

Throws:

NullPointerException - The given modification time is null.

See Also:

TimeStamp.TimeStamp(), TimeStamp.TimeStamp(java.util.Calendar)

getCreateTime

TimeStamp getCreateTime()

Returns the creation time of this mob, which is the date and time when this mob was originally created.

Returns:

Creation time for this mob.

setCreateTime

void setCreateTime(TimeStamp creationTime)
                   throws NullPointerException

Sets the creation time of this mob, which is the date and time when this mob was originally created. The creation time is initially set to the time that this mob was created. Therefore, this method should only be called to explicitly to change the creation time.

Parameters:

creationTime - The creation time for this mob.

Throws:

NullPointerException - The given creation time is null.

See Also:

TimeStamp.TimeStamp(), TimeStamp.TimeStamp(java.util.Calendar)

appendComment

void appendComment(@AAFString
                   String category,
                   @AAFString
                   String comment)
                   throws NullPointerException

Creates a user-defined comment and adds it to the collection of comments of this mob, which specify user comments that are directly classified and set up by the operator (for example Bin columns).

This method creates a new tagged value, initializes it with the specified comment name/value pair, and appends it to the comment collection.

Parameters:

category - The name associated with the new comment to create.

comment - The corresponding value, or description, of the new comment.

Throws:

NullPointerException - One or both of the name and/or value values is/are null.

See Also:

makeTaggedValue()

appendComment

void appendComment(TaggedValue comment)
                   throws NullPointerException

Append a user comment defined by an existing tagged value to the collection of user comments of this mob, which specify user comments that are directly classified and set up by the operator (for example Bin columns).

Parameters:

comment - User comment to append to the collection of user comments of this component.

Throws:

NullPointerException - The given user comment value is null.

See Also:

makeTaggedValue(), TaggedValueDefinition

countComments

@UInt32
int countComments()

Returns the total number of user comments attached to this mob, which specify user comments that are directly classified and set up by the operator (for example Bin columns).

Returns:

Total number of comments attached to this mob.

getComments

List<? extends TaggedValue> getComments()

Returns the collection of all comments attached to this mob, which specify user comments that are directly classified and set up by the operator (for example Bin columns).

Returns:

Shallow copy of the collection of all comments attached to this mob.

removeComment

void removeComment(TaggedValue comment)
                   throws NullPointerException,
                          ObjectNotFoundException

Removes the given user comment from the collection of user comments of this mob, which specify user comments that are directly classified and set up by the operator (for example Bin columns).

Parameters:

comment - User comment to remove from the collection of this mob.

Throws:

NullPointerException - The given tagged value user comment is null.

ObjectNotFoundException - The given comment is not in the collection of user comments of this mob.

appendNewTimelineSlot

TimelineMobSlot appendNewTimelineSlot(Rational editRate,
                                      Segment segment,
                                      @SlotID
                                      int slotId,
                                      @AAFString
                                      String slotName,
                                      @PositionType
                                      long origin)
                                      throws NullPointerException,
                                             IllegalArgumentException,
                                             SlotExistsException

Creates and returns a new timeline mob slot with the given property values, as well as appending it to this mob.

Parameters:

editRate - Units of time for the new timeline mob slot.

segment - Value for the new timeline mob slot.

slotId - Integer to be used to refer to the mob slot.

slotName - Name of the new timeline mob slot, or null to omit this optional property.

origin - Specifies the offset used to resolve source clip references to source material in the new timeline mob slot, measured in according to the edit rate of the new slot. A positive value means that the first sample of the essence is earlier than the zero position. A negative value of origin means that the zero position is earlier than the first sample of the essence.

Returns:

The newly created timeline mob slot, which is also appended to the list of mob slots of this mob.

Throws:

NullPointerException - One or more of the arguments is null.

IllegalArgumentException - The given slot id is negative.

SlotExistsException - The given slot is already used to to identify a slot in this mob.

offsetToMobTimecode

TimecodeValue offsetToMobTimecode(Segment timecodeSegment,
                                  @PositionType
                                  long offset)
                                  throws NullPointerException,
                                         TimecodeNotFoundException

Calculates the timecode at the given offset into the given timecode segment. If the given timecode segment is null, the method will search for the slot containing a timecode segment in this mob and will use that instead.

Parameters:

timecodeSegment - Timecode segment to search for, or null to select the one from this mob.

offset - Offset into the segment, expressed in edit unit's for the associated mob slot.

Returns:

Associated timecode for the given offset.

Throws:

NullPointerException - The given timecode segment is null.

TimecodeNotFoundException - A timecode slot was not found in this mob.

lookupSlot

MobSlot lookupSlot(@SlotID
                   int slotId)
                   throws SlotNotFoundException

Finds and returns the mob slot with the associated slot id from the list of slots for this mob.

Parameters:

slotId - The requested slot id from the list of slots of this mob.

Returns:

Matching mob slot.

Throws:

SlotNotFoundException - A mob slot with the given slot id was not found in this mob.

changeReference

void changeReference(MobID oldMobId,
                     MobID newMobId)
                     throws NullPointerException

Finds all source clips in this mob that refer to the specified old mob and changes the references to point to the newly specified mob.

This method traverses through all the mob reference chains of all of the slots of this mob looking for source clips. All source clips that have a source id property that matches the old mob id, changes them to the new mob id.

Parameters:

oldMobId - Mob id to match against the source id property of a source clip.

newMobId - If a match is found, change the mob id of the source clip to the given one.

Throws:

NullPointerException - One or both of the given mob ids is/are null.

See Also:

SourceReferenceSegment.getSourceID()

cloneExternal

Mob cloneExternal(Depend resolveDependencies,
                  IncludedMedia includedMedia,
                  AAFFile clonedFile)
                  throws NullPointerException

Clones this mob, and optionally all dependent mobs, to a mob that can be used in an external file, keeping the same mob id.

The method clones the specified this mob into a new destination mob, with the same mob id, in the given destination file. If the resolve dependencies flag is set to follow, the method also clones all mobs referenced by this mob.

If the include media flag is set, the method also copies the essence data associated with this mob and returns the destination mob, also cloning all private data. If the media data is not in the file, the function does not attempt to find it in another file and clone it. Both AAF files must be open before you call this function and both must have the same version number.

Parameters:

resolveDependencies - Sets whether the clone of this mob also clones all of its references.

includedMedia - Sets whether any media data included with this mob should be copied into the clone or not.

clonedFile - File in which to create the cloned mob.

Returns:

Externally valid cloned version of this mob, created according to the given parameters.

Throws:

NullPointerException - One or more of the given arguments is/are null and all are required.

copy

Mob copy(@AAFString
         String destMobName)
         throws NullPointerException

Creates and returns a new copy of this mob in the same AAF file. The method gives the returned new mob a new mob id and the given name. The method also copies all private data.

Parameters:

destMobName - Name for the newly created, copied version of this mob.

Returns:

Newly created copy of this mob.

Throws:

NullPointerException - The given destination name for the new mob is null.

appendKLVData

void appendKLVData(KLVData data)
                   throws NullPointerException

Appends an existing user KLV data item to the collection of KLV data items contained in this mob.

Parameters:

data - KLV data item to add to the collection of data items contained in this mob.

Throws:

NullPointerException - The given KLV data item is null.

See Also:

makeKLVData(), KLVDataDefinition

countKLVData

@UInt32
int countKLVData()

Returns the total number of KLV data items in the collection of KLV data items contained in this mob.

Returns:

Total number of KLV data items contained in this mob.

getKLVData

List<? extends KLVData> getKLVData()

Returns the collection of KLV data items contained in this mob.

Returns:

Shallow copy of the collection of KLV data items contained in this mob.

removeKLVData

void removeKLVData(KLVData data)
                   throws NullPointerException,
                          ObjectNotFoundException

Removes the given item of KLV data from the collection of KLV data items of this mob.

Parameters:

data - KLV data to remove from the set of KLV data of this mob.

Throws:

NullPointerException - Argument is null.

ObjectNotFoundException - The given KLV data object could not be found in the collection of KLV data items for this mob.

appendAttribute

void appendAttribute(@AAFString
                     String name,
                     @AAFString
                     String value)
                     throws NullPointerException

Create and append a new attribute to the collection of attributes contained in this mob, which specify attributes that are under the control of the application (for example filter control).

This method creates a new tagged value, initializes it with the specified attribute name/value pair, and appends it to the attribute collection.

Parameters:

name - Name of the new attribute.

value - Value of the new attribute.

Throws:

NullPointerException - One or both of the arguments is/are null.

See Also:

appendAttribute(TaggedValue)

appendAttribute

void appendAttribute(TaggedValue attribute)
                     throws NullPointerException

Appends an existing attribute to the collection of attributes contained in this mob, which specify attributes that are under the control of the application (for example filter control).

Parameters:

attribute - Attribute to append to the collection of attributes contained in this mob.

Throws:

NullPointerException - The given attribute is null.

See Also:

makeTaggedValue(), appendAttribute(String, String)

countAttributes

@UInt32
int countAttributes()

Returns the number of attributes in the collection of attributes contained in this mob, which specify attributes that are under the control of the application (for example filter control).

Returns:

Number of attributes in the collection of attributes contained in this mob.

getAttributes

List<? extends TaggedValue> getAttributes()

Returns the collection of attributes contained in this mob, which specify attributes that are under the control of the application (for example filter control).

Returns:

Shallow copy of the collection of attributes contained in this mob.

removeAttribute

void removeAttribute(TaggedValue attribute)
                     throws NullPointerException,
                            ObjectNotFoundException

Removes the given attribute from the collection of attributes contained in this mob, which specify attributes that are under the control of the application (for example filter control).

Parameters:

attribute - Attribute to remove from the collection of attributes contained in this mob.

Throws:

NullPointerException - The given attribute is null.

ObjectNotFoundException - The given attribute could not be found in collection of attributes contained in this mob.

setUsageCode

void setUsageCode(AUID usageCode)

Sets this mob's usage code, which specifies how this mob is used.

Possible values include:

• UsageType.AdjustedClip
• UsageType.LowerLevel
• UsageType.SubClip
• UsageType.Template
• UsageType.TopLevel

Set this optional property to null to omit it, which is used to specify that a clip references only file, import, tape or film sources.

The built-in usage codes are specified in the AAF edit protocol.

Parameters:

usageCode - This mob's usage code.

Throws:

NullPointerException - The given usage code is null.

See Also:

UsageType, TypeDefinitionExtendibleEnumeration.UsageType

getUsageCode

AUID getUsageCode()
                  throws PropertyNotPresentException

Returns the usage code for this mob, which specifies how this mob is used.

The built-in usage codes are specified in the AAF edit protocol.

Returns:

Usage code for this mob.

Throws:

PropertyNotPresentException - The optional usage code property is not present in this mob.

See Also:

UsageType, TypeDefinitionExtendibleEnumeration.UsageType

appendNewStaticSlot

StaticMobSlot appendNewStaticSlot(Segment segment,
                                  @SlotID
                                  int slotId,
                                  @AAFString
                                  String slotName)
                                  throws NullPointerException,
                                         IllegalArgumentException,
                                         SlotExistsException

Creates and returns a new static mob slot with the given property values, as well as appending it to the list of slots of this mob.

Parameters:

segment - Segment to use to create a new static mob slot.

slotId - Slot id to assign to the new static mob slot.

slotName - Name for the new static mob slot, or null to omit this optional property.

Returns:

Newly created static mob slot, which is also appended to the list of mob slots of this mob.

Throws:

NullPointerException - The given segment is null.

IllegalArgumentException - The given slot id is negative.

SlotExistsException - A mob slot with the given slot id is already present in this mob.

See Also:

appendSlot(MobSlot), makeStaticMobSlot()

appendNewEventSlot

EventMobSlot appendNewEventSlot(Rational editRate,
                                Segment segment,
                                @SlotID
                                int slotId,
                                @AAFString
                                String slotName)
                                throws NullPointerException,
                                       IllegalArgumentException,
                                       SlotExistsException

Creates and returns a new event mob slot with the given edit rate, as well as appending it to the list of slots of this mob.

Parameters:

editRate - Edit rate property for the new event mob slot.

segment - Segment for the new event mob slot.

slotId - Slot ID for the new event mob slot.

slotName - Name for the new event mob slot, or null to omit this optional property.

Returns:

The newly created event mob slot, which is also appended as a slot to the list of slots of this mob.

Throws:

NullPointerException - One or both of the edit rate and/or segment arguments is null.

IllegalArgumentException - The slot id is negative or the given segment is not valid according to the conditional rules for event mob slots.

SlotExistsException - A mob slot with the given slot id is already present in this mob.

See Also:

appendSlot(MobSlot), makeEventMobSlot()