tv.amwa.maj.argument
Class SourceReferenceValue

java.lang.Object
  tv.amwa.maj.argument.SourceReferenceValue

All Implemented Interfaces:

Serializable, Cloneable, XMLSerializable, SourceReferenceValue

public class SourceReferenceValue
extends Object
implements SourceReferenceValue, Serializable, XMLSerializable, Cloneable

Implementation of a source reference value that is a reference to an item of source material, defined by a mob id, source slot id and start time. This reference can be used as an argument to methods or as a return value. The class is used to ensure the constraint that if the source id is the zero mob id then the source slot id is 0 and the start time is 0 (SourceClip class specification text) .

The interpretation of a source reference value depends on the context where it is used. The value of a source reference can be explicit or relative to its context. Source references are often used to build a chain of references that can be used to trace the original source of some material.

Three different kinds of reference can be identified from the value of the source id property of a source reference. These are defined as:

1. Source id property is present and has a non-nil value. An explicit reference to a mob by its unique mob id and mob slot id. An optional offset starting frame may also be provided. Use the public constructor of this class to create this kind of source reference.
2. Source id property is present and is the zero mob id. This specifies that the source mob containing the source reference represents the original source material. Such references are the final link in source reference chains. To manufacture such a reference, call the originalSource() static method.
3. The source id property is not present. This specifies that the reference is to another slot within the same mob, the mob owning source reference itself. To manufacture such a reference, call one of the inContextReference(int) or inContextReference(int, Long) methods.

As this class is used as a convenience argument to the methods of other persistent classes, it has no persistent representation of its own.

Author:

Richard Cartwright

See Also:

SourceClip, SourceReferenceSegment, MobID, Serialized Form

Constructor Summary

SourceReferenceValue(MobID sourceID, int sourceSlotID, Long startTime)
Create a new source reference value that contains a source mob id, source slot id and start time.

Method Summary

void	appendXMLChildren(Node parent) Append child elements to the given parent node to serialize the value of an object to an XML fragment.
SourceReferenceValue	clone()
boolean	equals(Object o)
MobID	getSourceID() Returns the identifier of the mob being referenced.
int	getSourceSlotID() Returns the slot id of a mob slot within the referenced mob.
long	getStartTime() Returns the offset from the origin of the referenced mob's mob slot in edit units determined by the source clip's context.
int	hashCode()
static SourceReferenceValue	inContextReference(int sourceSlotID) Manufactures a new source reference to static material in slot within the same context as the mob in which the reference is specified.
static SourceReferenceValue	inContextReference(int sourceSlotID, Long startTime) Manufactures a new source reference to timeline- or event-based material in a slot within the same context as the mob in which the reference is specified.
boolean	isContextual() Returns true if this source reference is to another slot within the context of the same mob or false if it is a reference to a slot in another mob.
boolean	isOriginalSource() Return true if this source reference is to the original source material and false if it requires further resolution.
static SourceReferenceValue	originalSource() Manufactures a new source reference that indicates the reference is to essence that is the original source.
void	setPropertiesFromInterface(SourceReferenceValue castFrom) Set the properties of this source reference value using the given object that implements the SourceReferenceValue interface.
void	setSourceID(MobID sourceID) Sets the identity of mob being referenced.
void	setSourceSlotID(int sourceSlotID) Sets the slot id of the referenced mob slot within the referenced mob.
void	setStartTime(Long startTime) Returns the offset from the origin of the referenced mob's mob slot in edit units determined by the source clip's context.
String	toString() Create a pseudo-XML representation of this source reference, similar to that produced for a source clip.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SourceReferenceValue

public SourceReferenceValue(@MobIDType
                            MobID sourceID,
                            @SlotID
                            int sourceSlotID,
                            @PositionType
                            Long startTime)
                     throws IllegalArgumentException

Create a new source reference value that contains a source mob id, source slot id and start time. If the given source mob id is the null mob, values for source slot id and start time are set to zero to comply with source reference constraints.

Parameters:

sourceID - Identifies the mob being referenced. If the property is set to the zero mob id, it means that the mob owning the source reference describes the original source. If this optional property is omitted by setting its value to null, the given mob slot refers to another slot within the same mob.

sourceSlotID - Specifies the slot id of a mob slot within the specified mob. If the source id is the zero mob id, then the source mob slot id shall have a 0 value.

startTime - Specifies the offset from the origin of the referenced mob's mob slot in edit units determined by the associated source clip's context. If the source id is the zero id, then the start time shall have a 0 value. Set the value to null to omit this optional property in the case that the new reference is to static material.

Throws:

IllegalArgumentException - The source slot id cannot be set to a negative value.

See Also:

MobID.isZero(), MobID.getZeroMobID()

Method Detail

originalSource

public static final SourceReferenceValue originalSource()

Manufactures a new source reference that indicates the reference is to essence that is the original source. The source id will be the zero mob id, the source slot id will be zero and so will the start time.

Returns:

Manufactured source reference to original source.

See Also:

SourceReferenceValue.isOriginalSource(), MobID.isZero()

inContextReference

public static final SourceReferenceValue inContextReference(@SlotID
                                                            int sourceSlotID)
                                                     throws IllegalArgumentException

Manufactures a new source reference to static material in slot within the same context as the mob in which the reference is specified. This method version omits the start time property - use inContextReference(int, Long) to set a start time value for timeline- or event-based material.

Parameters:

sourceSlotID - Slot to reference within the same mob that this reference is defined in.

Returns:

Manufactured contextual source reference.

Throws:

IllegalArgumentException - The given source slot id is a negative value.

See Also:

StaticMobSlot, SourceReferenceValue.isContextual()

inContextReference

public static final SourceReferenceValue inContextReference(@SlotID
                                                            int sourceSlotID,
                                                            @PositionType
                                                            Long startTime)
                                                     throws IllegalArgumentException

Manufactures a new source reference to timeline- or event-based material in a slot within the same context as the mob in which the reference is specified. Use the inContextReference(int) to create a reference to static material.

Parameters:

sourceSlotID - Slot to reference within the same mob that this reference is defined in.

startTime - Specifies the offset from the origin of the referenced mob mobslot in edit units determined by the associated source clip object's context.

Returns:

Manufactured contextual source reference.

Throws:

IllegalArgumentException - The source slot id cannot be set to a negative value.

See Also:

TimelineMobSlot, EventMobSlot, SourceReferenceValue.isContextual()

setPropertiesFromInterface

public final void setPropertiesFromInterface(SourceReferenceValue castFrom)

Set the properties of this source reference value using the given object that implements the SourceReferenceValue interface.

Parameters:

castFrom - Object to use to set the values of this object.

getSourceID

@MobIDType
public MobID getSourceID()
                  throws PropertyNotPresentException

Description copied from interface: SourceReferenceValue

Returns the identifier of the mob being referenced. If the property is the zero mob id, it means that the mob owning this source reference describes the original source.

Specified by:

getSourceID in interface SourceReferenceValue

Returns:

Source id component of the source reference.

Throws:

PropertyNotPresentException - The optional source id property is not present in this source reference, implying that the reference is to a slot in the same mob as the reference itself.

setSourceID

public void setSourceID(@MobIDType
                        MobID sourceID)

Description copied from interface: SourceReferenceValue

Sets the identity of mob being referenced. If the property is the zero mob id, it means that the mob owning this source reference describes the original source. Set the source id to null to indicate that the reference is to a slot in the mob owning this reference.

Specified by:

setSourceID in interface SourceReferenceValue

Parameters:

sourceID - Source id component of the source reference.

getSourceSlotID

@SlotID
public int getSourceSlotID()

Description copied from interface: SourceReferenceValue

Returns the slot id of a mob slot within the referenced mob. If the source id of this value is the zero mob id then the source mob slot value shall also be set to 0.

Specified by:

getSourceSlotID in interface SourceReferenceValue

Returns:

Slot component of the source reference, specified by slot id.

setSourceSlotID

public void setSourceSlotID(@SlotID
                            int sourceSlotID)
                     throws IllegalArgumentException

Description copied from interface: SourceReferenceValue

Sets the slot id of the referenced mob slot within the referenced mob. If the source id of this value is the zero mob id then the source slot value shall also be set to 0.

Specified by:

setSourceSlotID in interface SourceReferenceValue

Parameters:

sourceSlotID - Slot component of source reference, specified by slot id.

Throws:

IllegalArgumentException - Trying to set a non-zero value when the source id is the zero mob id or the slot id is negative.

getStartTime

@PositionType
public long getStartTime()
                  throws PropertyNotPresentException

Description copied from interface: SourceReferenceValue

Returns the offset from the origin of the referenced mob's mob slot in edit units determined by the source clip's context. If the source id of this value is the nil mob id, then the start time shall also be set to 0.

Specified by:

getStartTime in interface SourceReferenceValue

Returns:

Offset from the origin of the referenced content.

Throws:

PropertyNotPresentException - The optional start time property is not present, indicating that the reference is in the context of a static mob slot rather than a timeline or event mob slot.

setStartTime

public void setStartTime(@PositionType
                         Long startTime)
                  throws IllegalArgumentException

Description copied from interface: SourceReferenceValue

Returns the offset from the origin of the referenced mob's mob slot in edit units determined by the source clip's context. If the source id of this value is the null mob id then the start time shall be set to 0.

Set this optional property to null to omit it, indicating that this reference is in the context of a static mob slot rather than a timeline or event mob slot.

Specified by:

setStartTime in interface SourceReferenceValue

Parameters:

startTime - Offset from the origin of the referenced content.

Throws:

IllegalArgumentException - Trying to set a non-zero value when the source id is the zero mob id.

isOriginalSource

public boolean isOriginalSource()

Description copied from interface: SourceReferenceValue

Return true if this source reference is to the original source material and false if it requires further resolution.

Specified by:

isOriginalSource in interface SourceReferenceValue

Returns:

Is this reference to the original source material?

See Also:

SourceReferenceValue.isOriginalSource(), originalSource()

isContextual

public boolean isContextual()

Description copied from interface: SourceReferenceValue

Returns true if this source reference is to another slot within the context of the same mob or false if it is a reference to a slot in another mob.

Specified by:

isContextual in interface SourceReferenceValue

Returns:

Is this reference to another slot in the context of the same mob?

See Also:

SourceReferenceValue.isContextual(), inContextReference(int), inContextReference(int, Long)

equals

public boolean equals(Object o)

Overrides:

equals in class Object

toString

public String toString()

Create a pseudo-XML representation of this source reference, similar to that produced for a source clip. No XML schema or DTD defines this element. For example, an original source reference would create the following:

 <?xml version=\"1.0\" encoding=\"UTF-8\"?>
 <!--The SourceReferenceValue tag is not valid AAF XML.-->
 <SourceReferenceValue>
   <SourceID>urn:x-umid:000000000000000000000000-00-000000-00000000000000000000000000000000</SourceID>
   <SourceMobSlotID>0</SourceMobSlotID>
   <StartTime>0</StartTime>
 </SourceReferenceValue>
 

Overrides:

toString in class Object

Returns:

An XML representation of this source reference.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

clone

public SourceReferenceValue clone()

Overrides:

clone in class Object

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

Parameters:

parent - XML parent element to append child nodes to.