Overview  Package   Class  Tree  Deprecated  Index 
Media Authoring
with Java API
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

tv.amwa.maj.entity
Class SourceMob

java.lang.Object
  extended by tv.amwa.maj.entity.InterchangeObject
      extended by tv.amwa.maj.entity.Mob
          extended by tv.amwa.maj.entity.SourceMob
All Implemented Interfaces:
Serializable, Cloneable, MAJCommon, InterchangeObject, Mob, SearchSource, SourceMob, XMLSerializable
@AAFClass(uuid1=218169601,
          uuid2=257,
          uuid3=14080,
          uuid4={6,14,43,52,2,6,1,1},
          definedName="SourceMob",
          description="The SourceMob class describes essence that is either stored in a digital form in a file or stored on a physical media, such as tape or film.")
public class SourceMob
extends Mob
implements SourceMob, Serializable, Cloneable, MAJCommon

Implements the description of essence that is either stored in a digital form in a file or stored on a physical media, such as tape or film. The description is provided by an essence descriptor, which is either a tape descriptor, file descriptor, film descriptor, or some extended descriptor.

THE COMMENTS FOR THIS CLASS ARE INCOMPLETE.

Author:
Richard Cartwright
See Also:
Serialized Form

Nested Class Summary
static class SourceMob.EssenceDescriptionXMLHandler
           
static class SourceMob.XMLHandler
           
 
Nested classes/interfaces inherited from class tv.amwa.maj.entity.Mob
Mob.MobAttributesXMLHandler, Mob.MobKLVDataXMLHandler, Mob.MobUserCommentsXMLHandler, Mob.SlotsXMLHandler
 
Nested classes/interfaces inherited from class tv.amwa.maj.entity.InterchangeObject
InterchangeObject.InterchangeObjectXMLHandler
 
Field Summary
static String SOURCEMOB_TAG
           
 
Fields inherited from class tv.amwa.maj.entity.Mob
MOB_ITEM
 
Fields inherited from interface tv.amwa.maj.iface.SourceMob
FULL_RANGE
 
Constructor Summary
SourceMob(MobID mobID, String name, EssenceDescriptor essenceDescription)
          Creates and initializes a new source mob, which describes essence that is either stored in a digital form in a file or stored on a physical media, such as tape or film.
 
Method Summary
 void addNilReference(int slotID, long length, DataDefinition dataDefinition, Rational editRate)
          Adds a slot containing an original source reference to this source mob.
 void addPulldownReference(AppendOption addType, Rational editRate, int slotID, DataDefinition essenceKind, SourceReferenceValue reference, long sourceReferenceLength, PulldownKindType pulldownKind, int phaseFrame, PulldownDirectionType direction)
          Connects the given source mob with the physical source mob that describes the previous generation of essence, with an additional pulldown as part of the reference to indicate a non 1 to 1 relationship between the two.
 void addStaticNilReference(int slotId, DataDefinition dataDefinition)
           
 void appendEdgecodeSlot(Rational editRate, int slotID, long startEC, long length, FilmType filmKind, EdgeType codeFormat, byte[] header)
          Creates and adds an edgecode slot to the film mob represented by this source mob, with the given starting edgecode, length and edit rate.
 void appendPhysicalSourceReference(Rational editRate, int slotID, DataDefinition essenceKind, SourceReferenceValue reference, long sourceReferenceLength)
          Connects this source mob with the physical source mob that describes the previous generation of essence, appending it to the existing mob chain.
 void appendTimecodeSlot(Rational editRate, int slotID, TimecodeValue startTC, long length)
          Creates and adds a timecode slot to a tape mob represented by this source mob, with the given starting timecode, length and edit rate.
 void appendXMLChildren(Node parent)
          Append child elements to the given parent node to serialize the value of an object to an XML fragment.
 SourceMob clone()
          Creates a cloned copy of this entity.
 EssenceDescriptor getEssenceDescriptor()
          Returns the essence descriptor of this source mob, which describes the format of the essence associated with the source mob.
 void newPhysicalSourceReference(Rational editRate, int slotID, DataDefinition essenceKind, SourceReferenceValue reference, long sourceReferenceLength)
          Connects this source mob with the physical source mob that describes the previous generation of essence, appending it to the existing mob chain.
 List<FindSourceInformation> searchSource(int slotID, long offset, MobKind mobKind, CriteriaType mediaCriteria, OperationChoice operationChoice)
          Returns the source information for a slot in a master mob or source mob.
 void setEssenceDescriptor(EssenceDescriptor essenceDescriptor)
          Sets the essence descriptor of this source mob, which describes the format of the essence associated with the source mob.
 void setPropertiesFromInterface(SourceMob castFrom)
           
 void specifyValidCodeRange(DataDefinition essenceKind, int slotID, Rational editRate, long startOffset, long length)
          Creates and adds a slot containing source clips to the source mob to indicate that a (recently added) timecode slot or edgecode slot is valid for that channel.
 
Methods inherited from class tv.amwa.maj.entity.Mob
appendAttribute, appendAttribute, appendComment, appendComment, appendKLVData, appendNewEventSlot, appendNewStaticSlot, appendNewTimelineSlot, appendSlot, changeReference, cloneExternal, copy, countAttributes, countComments, countKLVData, countSlots, equals, getAttributes, getComments, getCreateTime, getKLVData, getMobID, getModTime, getName, getSlotAt, getSlots, getUsageCode, hashCode, insertSlotAt, lookupSlot, offsetToMobTimecode, prependSlot, removeAttribute, removeComment, removeKLVData, removeSlotAt, setCreateTime, setMobID, setModTime, setName, setPropertiesFromInterface, setUsageCode
 
Methods inherited from class tv.amwa.maj.entity.InterchangeObject
castFromInterface, countProperties, createOptionalPropertyValue, disableGenerationTracking, enableGenerationTracking, getDefinition, getGeneration, getGenerationAUID, getProperties, getPropertyValue, isGenerationTracked, isPropertyPresent, omitOpionalProperty, registerImplementation, setPropertiesFromInterface, setPropertyValue, toString
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface tv.amwa.maj.iface.Mob
appendAttribute, appendAttribute, appendComment, appendComment, appendKLVData, appendNewEventSlot, appendNewStaticSlot, appendNewTimelineSlot, appendSlot, changeReference, cloneExternal, copy, countAttributes, countComments, countKLVData, countSlots, getAttributes, getComments, getCreateTime, getKLVData, getMobID, getModTime, getName, getSlotAt, getSlots, getUsageCode, insertSlotAt, lookupSlot, offsetToMobTimecode, prependSlot, removeAttribute, removeComment, removeKLVData, removeSlotAt, setCreateTime, setMobID, setModTime, setName, setUsageCode
 
Methods inherited from interface tv.amwa.maj.iface.InterchangeObject
countProperties, createOptionalPropertyValue, disableGenerationTracking, enableGenerationTracking, getDefinition, getGeneration, getGenerationAUID, getProperties, getPropertyValue, isGenerationTracked, isPropertyPresent, omitOpionalProperty, setPropertyValue
 
Methods inherited from interface tv.amwa.maj.entity.MAJCommon
equals, hashCode, toString
 

Field Detail

SOURCEMOB_TAG

public static final String SOURCEMOB_TAG
See Also:
Constant Field Values
Constructor Detail

SourceMob

public SourceMob(MobID mobID,
                 @AAFString
                 String name,
                 EssenceDescriptor essenceDescription)
          throws NullPointerException

Creates and initializes a new source mob, which describes essence that is either stored in a digital form in a file or stored on a physical media, such as tape or film. The required properties of creation time and last modified time will be set automatically to the time of calling this method. These timestamp values can be set manually by calling setCreateTime() and and setModTime().

Parameters:
mobID - Unique identifier for the mob.
name - Name of the composition mob.
essenceDescription - Describes the format of the essence associated with thw new source mob.
Throws:
NullPointerException - The mob id and/or essence description arguments are null.
Method Detail

setPropertiesFromInterface

public final void setPropertiesFromInterface(SourceMob castFrom)
See Also:
InterchangeObject.setPropertiesFromInterface(tv.amwa.maj.iface.InterchangeObject)

getEssenceDescriptor

@AAFProperty(uuid1=100729092,
             uuid2=515,
             uuid3=0,
             uuid4={6,14,43,52,1,1,1,2},
             definedName="EssenceDescription",
             typeName="StrongReference to EssenceDescriptor",
             optional=false,
             uniqueIdentifier=false,
             pid=18177)
public EssenceDescriptor getEssenceDescriptor()
Description copied from interface: SourceMob

Returns the essence descriptor of this source mob, which describes the format of the essence associated with the source mob.

Specified by:
getEssenceDescriptor in interface SourceMob
Returns:
Essence descriptor of this source mob.

setEssenceDescriptor

public void setEssenceDescriptor(EssenceDescriptor essenceDescriptor)
                          throws NullPointerException
Description copied from interface: SourceMob

Sets the essence descriptor of this source mob, which describes the format of the essence associated with the source mob.

Specified by:
setEssenceDescriptor in interface SourceMob
Parameters:
essenceDescriptor - Essence descriptor of this source mob.
Throws:
NullPointerException - The given essence descriptor is null.

addNilReference

public void addNilReference(int slotID,
                            long length,
                            DataDefinition dataDefinition,
                            Rational editRate)
                     throws NullPointerException,
                            IllegalArgumentException,
                            BadRateException,
                            BadLengthException,
                            SlotExistsException
Description copied from interface: SourceMob

Adds a slot containing an original source reference to this source mob. This special source id indicates that the mob chain ends here, which indicates that no further record exists of where the essence was derived from. Some source clip is still required on the track to indicate that the track exists and may be referenced from other mobs.

Examples of source mobs that are not derived from a previous source of essence are:

Specified by:
addNilReference in interface SourceMob
Parameters:
slotID - Slot id to be assigned to the new slot.
length - Duration of the source clip to be added to the new slot.
dataDefinition - Data definition for the new slot.
editRate - Edit rate for the new slot.
Throws:
NullPointerException - The given data definition and/or edit rate is/are null.
IllegalArgumentException - The given slot identifier is null
BadLengthException - The length cannot be a negative value.
BadRateException - The edit rate is not valid.
SlotExistsException - The given slot id matches that of a mob slot already present in this source mob.
See Also:
SourceReferenceValue.isOriginalSource()

addStaticNilReference

public void addStaticNilReference(int slotId,
                                  DataDefinition dataDefinition)
                           throws NullPointerException,
                                  IllegalArgumentException,
                                  SlotExistsException
Throws:
NullPointerException
IllegalArgumentException
SlotExistsException

addPulldownReference

public void addPulldownReference(AppendOption addType,
                                 Rational editRate,
                                 int slotID,
                                 DataDefinition essenceKind,
                                 SourceReferenceValue reference,
                                 long sourceReferenceLength,
                                 PulldownKindType pulldownKind,
                                 int phaseFrame,
                                 PulldownDirectionType direction)
                          throws NullPointerException,
                                 PulldownDirectionException,
                                 BadLengthException,
                                 NotSourceClipException,
                                 SlotExistsException
Description copied from interface: SourceMob

Connects the given source mob with the physical source mob that describes the previous generation of essence, with an additional pulldown as part of the reference to indicate a non 1 to 1 relationship between the two.

This is a helper method to create a slot with a pulldown object which references a source clip, which references a particular piece of media. This method takes many parameters because the components of a pulldown have been broken out as separate parameters.

The ancestor of a source mob described by a tape descriptor is often a film descriptor.

Specified by:
addPulldownReference in interface SourceMob
Parameters:
addType - Overwrite existing slot sequence, or create a new sequence and append it.
editRate - Edit rate of slot to contain the reference.
slotID - Slot ID for the slot to contain the reference.
essenceKind - Data kind of slot to contain reference. Requires a data kind valid for an essence stream. Valid data kinds are DataDefinitionConstant.Picture and DataDefinitionConstant.Sound.
reference - Reference to a physical source mob.
sourceReferenceLength - Length of the referenced physical source mob.
pulldownKind - Method of conversion used between this physical source mob and this source mob.
phaseFrame - Phase of the first frame.
direction - Direction of the pulldown operation.
Throws:
NullPointerException - One or more of the nullable arguments is/are null and all are required.
PulldownDirectionException - The given pullown direction is invalid in this context, for example tape to film speed when this is a tape source mob.
BadLengthException - The given source reference length cannot is negative.
NotSourceClipException - The existing contents of the given slot does not contain a source clip to add a pulldown reference to.
SlotExistsException - The given slot id matches that of a mob slot already present in this source mob.
See Also:
SourceClip, Pulldown, Sequence

appendEdgecodeSlot

public void appendEdgecodeSlot(Rational editRate,
                               int slotID,
                               long startEC,
                               long length,
                               FilmType filmKind,
                               EdgeType codeFormat,
                               byte[] header)
                        throws NullPointerException,
                               IllegalArgumentException,
                               BadLengthException,
                               BadSizeException,
                               FilmDescriptorOnlyException,
                               SlotExistsException
Description copied from interface: SourceMob

Creates and adds an edgecode slot to the film mob represented by this source mob, with the given starting edgecode, length and edit rate. It is also necessary to then add an essence slot with specifyValidCodeRange() to make the new edgecode slot valid.

Specified by:
appendEdgecodeSlot in interface SourceMob
Parameters:
editRate - Edit rate for the new edgecode slot.
startEC - Starting edgecode of the new edgecode slot.
length - Length of the new edgecode slot.
filmKind - Film kind for the new edgecode slot.
codeFormat - Code for the new edgecode slot.
header - Edgecode 8-byte header for the new edgecode slot.
Throws:
NullPointerException - One or more of the arguments is null.
BadLengthException - The length value is negative.
BadSizeException - The size of the header is not the required 8 bytes.
FilmDescriptorOnlyException - This operation is only valid for a source mob referencing a film descriptor.
SlotExistsException - The given slot id matches that of a mob slot already present in this source mob.
IllegalArgumentException
See Also:
makeEdgecodeValue(), EdgecodeValue specification, EdgecodeValue implementation

appendPhysicalSourceReference

public void appendPhysicalSourceReference(Rational editRate,
                                          int slotID,
                                          DataDefinition essenceKind,
                                          SourceReferenceValue reference,
                                          long sourceReferenceLength)
                                   throws NullPointerException,
                                          BadLengthException,
                                          InvalidDataDefinitionException,
                                          SlotExistsException
Description copied from interface: SourceMob

Connects this source mob with the physical source mob that describes the previous generation of essence, appending it to the existing mob chain. If a physical source mob, such as a file source mob or tape source mob, references another physical source mob as its ancestor, with no pulldown, then this function makes the connection between the two.

This is a helper method to create a slot with a source clip referencing a particular piece of media.

The ancestor of a source mob with a file descriptor is often a tape descriptor.

The essenceKind parameter requires a data kind valid for an essence stream. Valid data kinds are:

Specified by:
appendPhysicalSourceReference in interface SourceMob
Parameters:
editRate - Edit rate of the slot to contain the reference.
slotID - Slot ID of the slot to contain the reference.
essenceKind - Data kind of the slot to contain the reference.
reference - Reference to a physical source mob.
sourceReferenceLength - Length of the referenced source clip.
Throws:
NullPointerException - One or more of the nullable parameters is/are null and all are required.
BadLengthException - The source reference length is negative.
InvalidDataDefinitionException - The given data definition is not compatible with that of the slot this element will be appended to.
SlotExistsException - The given slot id matches that of a mob slot already present in this source mob.

appendTimecodeSlot

public void appendTimecodeSlot(Rational editRate,
                               int slotID,
                               TimecodeValue startTC,
                               long length)
                        throws NullPointerException,
                               IllegalArgumentException,
                               TapeDescriptorOnlyException,
                               SlotExistsException
Description copied from interface: SourceMob

Creates and adds a timecode slot to a tape mob represented by this source mob, with the given starting timecode, length and edit rate. It is then necessary to call specifyValidCodeRange() to add the filler to the other essence slots to indicate that the timecode is valid for that other slots (tracks) of this mob.

The start timecode parameter is expressed in frames since midnight. The length parameter can be the value SourceMob.FULL_RANGE, in which case the length is 24 hours.

Specified by:
appendTimecodeSlot in interface SourceMob
Parameters:
editRate - Edit rate of the timecode slot.
slotID - Slot id for the new timecode slot.
startTC - Starting timecode for the timecode slot.
length - Duration of the new timecode slot.
Throws:
NullPointerException - One or both of the edit rate and/or start timecode arguments is/are null.
TapeDescriptorOnlyException - This operation is only valid for a source mob referencing a tape descriptor.
SlotExistsException - The given slot id matches that of a mob slot already present in this source mob.
IllegalArgumentException
See Also:
SourceMob.FULL_RANGE, makeTimecodeValue(), TimecodeValue specification, TimecodeValue implementation

newPhysicalSourceReference

public void newPhysicalSourceReference(Rational editRate,
                                       int slotID,
                                       DataDefinition essenceKind,
                                       SourceReferenceValue reference,
                                       long sourceReferenceLength)
                                throws NullPointerException,
                                       BadLengthException,
                                       SlotExistsException
Description copied from interface: SourceMob

Connects this source mob with the physical source mob that describes the previous generation of essence, appending it to the existing mob chain. If a physical source mob, such as a file source mob or tape source mob, references another physical source mob as its ancestor, with no pulldown, then this function makes the 1 to 1 connection between the two.

This is a helper method to create a slot with a source clip referencing a particular piece of media.

The ancestor of a source mob with a file descriptor is often a tape descriptor.

The essence kind parameter requires a data kind valid for an essence stream. Valid data kinds are:

Specified by:
newPhysicalSourceReference in interface SourceMob
Parameters:
editRate - Edit rate of the slot to contain the reference.
slotID - Slot id of the slot to contain the reference.
essenceKind - Data kind of the slot to contain the reference.
reference - Reference to a physical source mob.
sourceReferenceLength - Length of the referenced source clip.
Throws:
NullPointerException - One or more of the nullable arguments is/are null and all are required.
BadLengthException - The given source reference length is negative.
SlotExistsException - The given slot id matches that of a mob slot already present in this source mob.
See Also:
SourceClip

specifyValidCodeRange

public void specifyValidCodeRange(DataDefinition essenceKind,
                                  int slotID,
                                  Rational editRate,
                                  long startOffset,
                                  long length)
                           throws NullPointerException,
                                  BadLengthException,
                                  SlotExistsException
Description copied from interface: SourceMob

Creates and adds a slot containing source clips to the source mob to indicate that a (recently added) timecode slot or edgecode slot is valid for that channel.

The essence kind parameter requires a data kind with valid for an essence stream. Valid data kinds are:

Specified by:
specifyValidCodeRange in interface SourceMob
Parameters:
essenceKind - Data kind for the slot to be added.
slotID - Slot id for the slot to be added.
editRate - Edit rate for the slot to be added.
startOffset - Start offset for the slot to be added.
length - Duration of the source clip in the slot.
Throws:
NullPointerException - One or both of the edit rate and/or essence kind arguments is/are null.
BadLengthException - The given length for the new source clip is negative.
SlotExistsException - The given slot id matches that of a mob slot already present in this source mob.

searchSource

public List<FindSourceInformation> searchSource(int slotID,
                                                long offset,
                                                MobKind mobKind,
                                                CriteriaType mediaCriteria,
                                                OperationChoice operationChoice)
                                         throws NullPointerException,
                                                InvalidMobTypeException,
                                                TraversalNotPossibleException
Description copied from interface: SearchSource

Returns the source information for a slot in a master mob or source mob. The method follows the source clip references in the specified slot until it encounters the kind of mob specified in the mob kind parameter.

This function cannot be used on a composition mob and is not intended to be called iteratively.

Specified by:
searchSource in interface SearchSource
Parameters:
slotID - Slot to find source information for.
offset - Offset into the slot.
mobKind - Kind of mob to search for.
mediaCriteria - Media criteria to match in the search.
operationChoice - Operation choice.
Returns:
List of source information matching the given search criteria.
Throws:
NullPointerException - One or more of the arguments is null.
InvalidMobTypeException - The given mob type is not valid.
TraversalNotPossibleException - A mob of the given kind cannot be found.

clone

public SourceMob clone()
Description copied from interface: MAJCommon

Creates a cloned copy of this entity. The clone will be initialized to have the same value as this value but exists independently from then on. Changes to this value will not effect the clone and changes to the clone will not effect this. MAJ API clones are true deep clones with no shared references to areas of memory within the original.

This method does not throw a CloneNotSupportedException as all entity values must implement the Cloneable interface. If a cloning error does occur, a null value will be returned but this is very unlikely to happen.

Specified by:
clone in interface MAJCommon
Overrides:
clone in class Mob
Returns:
Independent clone of this value, which is a deep copy.
See Also:
Object.clone()

appendXMLChildren

public void appendXMLChildren(Node parent)
Description copied from interface: XMLSerializable

Append child elements to the given parent node to serialize the value of an object to an XML fragment. Methods of the XMLBuilder class are provided to help with this process.

Specified by:
appendXMLChildren in interface XMLSerializable
Overrides:
appendXMLChildren in class Mob
Parameters:
parent - XML parent element to append child nodes to.
Overview  Package   Class  Tree  Deprecated  Index 
Media Authoring
with Java API
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
(c) 2007-2008 Richard Cartwright, all rights reserved. Subject to the terms of the AAF SDK Public Source License.